We build a product that finds stale documentation, so it would be commercially convenient to imply that documentation staleness is an unsolvable problem you need software for. It is not. A lot of it is a writing problem, and the writing fixes are cheap.
These come out of reading a few thousand documentation pages against the changes that broke them. They are ordered by how much decay they prevent per unit of effort.
1. State a value once
The most common cause of a page contradicting itself is the same number appearing three times: in the prose, in a code sample, and in a table of options. When the default moves, someone updates two of the three.
Pick the one place a value lives. Usually that is the options table, because it is scannable. Then have the prose refer to it rather than repeat it: "three attempts by default" becomes "the default number of attempts", and the reader looks at the table. You lose a small amount of immediacy. You lose a large amount of drift.
2. Generate code samples from tests
A code sample in a documentation page is untested code, sitting next to a test suite, in the same repository. This is an odd arrangement that everyone accepts.
<!-- docs/guides/retries.md -->
```ts file=../examples/retry-basic.ts
```Point the sample at a file that the test suite imports and runs. Now a rename breaks CI instead of breaking a reader. This single habit accounted for the largest difference in decay rate between the repositories we studied.
3. Name the version you are describing
A page that says "the client supports streaming" is either true or false depending on when you read it, and there is no way for the reader to tell which. A page that says "since 4.2, the client supports streaming" stays true forever. The claim is now anchored.
This costs four words and converts an expiring statement into a permanent one. It is the highest-leverage sentence-level habit on this list.
4. Separate the concepts from the specifics
Our corpus work found that pages stating many concrete values decay roughly fourteen times faster than pages stating few. That is a strong enough effect to organise around.
Put the explanation of why retries work the way they do in one page, and the table of retry options in another. The conceptual page will need touching once a year. The reference page will need touching every release, and now you know which one to check.
- Concept pages: why it works this way, what the trade-offs are, when not to use it. Almost no literals.
- Reference pages: every parameter, every default, every error code. Almost nothing but literals.
- Guides: a path through a task. These are the hardest to keep correct because they mix both, so keep them short and make their code samples transcluded.
5. Write the error message, not a description of it
"You will see an error about an invalid token" is unsearchable. The reader arrived at your page by pasting the error into a search box, and the error was:
Error: token signature verification failed (kid=v2, alg=HS256)Paste the real string. It makes the page findable, and it makes the page mechanically checkable: a change to that error string can be matched against the docs. Descriptions of errors cannot be matched against anything.
6. Give every page an owner in the file
Not a CODEOWNERS entry — those go stale too, and nobody reads them while editing. A line of front matter at the top of the page.
---
title: Verifying webhook signatures
owner: platform-team
reviewed: 2026-05-04
---The reviewed date is the useful half. It does not assert that the page is correct; it asserts when a human last looked. A page with a reviewed date eighteen months old and a busy code path underneath it is the first thing to audit, and you can find all of them with a grep.
7. Delete more
In our corpus, 11% of wrong pages were never corrected — they were eventually deleted. In almost every case the deletion should have happened much earlier, and the page spent a year or more misleading people because deleting documentation feels like destroying work.
A page describing a feature two versions dead is worse than no page. It ranks in search, it looks authoritative, and it costs a reader an afternoon. If you are not going to maintain it, remove it and leave a redirect to whatever replaced it.
What none of this fixes
All seven habits reduce the rate at which pages go wrong. None of them tell you which pages are wrong right now, and none of them help with the change made by someone who has never opened the docs directory and does not know that a page three folders away describes the constant they just edited.
That is the part we built a product for. But if you do these seven things first, you will need less of it, and the drafts you do get will be smaller and easier to approve. We would rather say that than pretend the tool is the whole answer.