Most documentation is accurate on the day it's written and wrong within a quarter. Writers aren't careless. Docs describe a system that keeps changing while the docs stay still.
This is a structure for documentation that survives the author leaving, the system evolving, and six months of nobody reading closely enough to notice it's wrong. Each step names the framework or tool that makes it easy to enforce instead of easy to forget.
Prerequisites
A codebase with at least one component worth documenting
Write access to wherever your docs live: repo, wiki, or a dedicated docs site
Fifteen minutes to restructure before you write another word
Step 1: Split by half-life
Most docs mix three kinds of content on one page: things that never change, things that change occasionally, and things that change every release. Separate them.
Stable: architecture decisions, core concepts, the reasoning behind a system. Write these as Architecture Decision Records: one page per decision, covering context, decision, and consequences. adr-tools generates and numbers them from the command line, and they live in the repo next to the code they justify.
Semi-stable: API contracts, configuration options, integration points. Generate these from code. TypeDoc for TypeScript, Sphinx for Python, godoc for Go. A generated reference can't drift from the code. It's a rendering of the code, refreshed on every build.
Volatile: current version numbers, active limitations, in-progress features. Belongs in a changelog or a pinned issue, where its temporary nature is obvious.
If you want the framework behind this split, it's Diátaxis: tutorials, how-to guides, reference, and explanation are four distinct jobs, and a doc trying to do two of them fails at both. Half-life is a rough proxy for which of the four a given page actually is.
Step 2: Put ownership in the file
Every doc needs a named owner and a last-reviewed date, visible at the top:
---
owner: platform-team
last_reviewed: 2026-03-15
review_cadence: quarterly
---
Docs without an owner get orphaned the moment their author changes teams. Nobody feels responsible, so nobody updates them, and a new hire six months later follows instructions describing a system that no longer exists.
At a handful of services this frontmatter is enough. Past a dozen, Backstage TechDocs turns the same metadata into a searchable catalog wired directly into your service registry, so ownership becomes queryable.
Step 3: Link to source
Anything that already exists in code should be referenced.
Wrong:
The API accepts these parameters: limit (default 20), offset (default 0), sort (default "created_at")
Right:
Parameters are defined in `api/schemas/pagination.ts`. See inline JSDoc for defaults.
The first version is wrong the moment someone changes a default in code and forgets the doc exists. The second version can't be wrong, because it isn't claiming anything the code itself isn't already claiming. This costs a reader one extra click. That's a fair trade for a doc that can't drift.
Step 4: Enforce consistency with a linter
A style guide is a document about documents. Nobody checks it before shipping a page.
Vale is an open-source prose linter that runs in CI the same way ESLint runs against code. Point it at a folder of docs, define banned terms, deprecated product names, and terminology rules, and it fails the build the same way a broken test does. This is the only way house style survives past the person who wrote the style guide.
Step 5: Write the failure mode
Most docs explain how something works when everything goes right. The valuable ten minutes come when something breaks and the doc either has the answer or doesn't.
For every setup or integration doc, add a section named exactly this:
## When this breaks
List the three most common failure modes, their symptoms, and their fixes. This section ages better than the setup instructions above it, because failure modes are usually structural and don't shift every release the way configuration does.
Step 6: Delete on a schedule
Tie a recurring check to each doc's review_cadence. A short script reads the last_reviewed date in the frontmatter. If it's overdue, the script opens an issue. This takes under an hour to write, and it turns review from something people forget into something that finds them.
When the issue fires, the owner has three options: confirm the doc is still accurate, update it, or delete it. Deletion is underused. A wrong doc costs more than no doc — it stays trusted until it costs someone an afternoon. No doc just sends the reader to the source, slower but honest.
What this costs
This setup takes longer than one markdown file with everything crammed in. ADRs mean writing decisions down as they happen. Vale means someone maintains a rules file. Ownership metadata means someone actually owns something. Scheduled review adds noise to a calendar and an issue tracker.
The alternative costs more. A wiki nobody trusts is a wiki nobody opens. A codebase with no trusted docs pushes every question onto the two or three engineers who've been there long enough to remember.
Rot is inevitable. Neglect is optional.