October 27, 2025·4 min read
Docs people actually read
Documentation fails as literature because nobody reads it as literature. Writing for the person who arrived mid-panic, from a search result.
Nobody reads documentation. People raid it. They arrive from a search result, mid-task and slightly annoyed, scan for the shape of their answer, and leave the moment they have it. Once you accept this — that docs are a rescue service, not a book — most of the craft follows.
Write for the raid
The reader gave you one glance to prove they are on the right page. Spend it. Lead every page with the outcome: what this does, when you would want it, and the shortest working example. Prose that clears its throat — "In this article, we will explore…" — is prose that loses the raid.
- Put the answer first and the theory after it, for the second visit.
- Make every heading a claim, so the sidebar reads as a summary.
- Show a complete, runnable example before any partial ones.
- Name errors verbatim — the exact string is what people search.
The example is the contract
Readers trust code blocks over sentences, and they are right to: the sentence can drift, but the example either runs or it does not. Treat samples as production code — tested, current, copy-pasteable without edits. One stale example poisons a whole page, because the reader who catches it stops believing everything else.
Maintenance is the feature
Docs rot faster than code because nothing breaks when they lie. Wire them into the loop that keeps code honest: docs ship in the same pull request as the change, examples run in CI, and every support question that reveals a gap becomes a small edit the same week. A modest, true page beats an impressive, stale one every time.
The reward for all this is quiet. Nobody praises documentation that works — they find the answer, close the tab, and get on with their afternoon. That closed tab is the five-star review.