I write documentation for a living in the loosest sense: I run a small niche content site on my own, and most of its pages are reference pages. Somebody arrives with one question, wants one answer, and leaves. For a long time I wrote those pages like essays — a bit of background, a bit of history, the answer somewhere in the middle if you were patient enough to find it.
Then I rewrote one page properly, and it changed how I think about every page I write now, including the technical notes I keep for myself.
A reference page is a contract, not an essay
The useful mental model, borrowed shamelessly from API design, is this: the reader arrives with a single call in mind. They want to know what a thing is, what it does, and how to use it — in that order, without ceremony.
If the first paragraph does not answer the question, the page has already failed, however well written the rest of it is. Nobody opens a reference page to be persuaded. They open it to be oriented, and then to act.
That sounds obvious. It took me an embarrassing number of pages to actually honour it.
The four-part shape that finally worked
The page that clicked for me follows a shape I now reuse everywhere:
1. A definition in plain language. One paragraph, no jargon that needs its own explanation. If the definition needs a glossary, it is not a definition yet.
2. Scope and boundaries. What the thing is, and just as importantly what it is not. Most confusion I see in documentation — mine included — is not a lack of information. It is a reader applying the right concept to the wrong case, because nobody told them where the concept stops.
3. Concrete usage. Not a list of possibilities, but the exact words, commands, or steps a person would use in real life. Vague advice is worse than no advice, because it looks complete while leaving the reader to guess.
4. What happens over time. How long the answer stays true, what degrades first, and when to come back. A reference page that pretends nothing changes is lying by omission.
The clearest example I have is a guide to the taper fade: it starts by separating a taper from a full fade, then names exactly where the taper lives, gives the reader the words to use when asking for it, and ends with how long it holds its shape before it needs attention. The structure is doing the work, not the prose.
What I stopped doing
Three habits, all of which felt like good writing at the time:
Opening with history. Interesting, sometimes, but it delays the answer and tells the reader this page is about the author's knowledge rather than their problem. History goes at the end now, if it goes anywhere.
Covering every edge case up front. Edge cases belong in a clearly marked section after the main path, not woven into the definition. When everything is equally prominent, nothing is findable.
Writing for the reader who already agrees. I used to write as if the reader had arrived convinced. In practice, the reader who most needs a reference page is the one who is unsure, or who has heard two conflicting versions. Writing for that person — naming the confusion directly, then resolving it — made the pages measurably more useful, because it answered the question they actually typed.
A test I run before publishing
Before a reference page goes out, I ask three questions:
- Can a stranger state the answer in one sentence after thirty seconds?
- Can they act on it without re-reading the page?
- Can they tell when it no longer applies to them?
If any answer is no, the page is not finished, no matter how polished it reads. Usually the fix is not more writing. It is moving one paragraph to the top, deleting one paragraph entirely, or adding a single sentence that says "this is not for you if…"
That last sentence is the most underrated line in documentation. It costs nothing, and it saves the reader who was about to follow the wrong instructions entirely.
Why this matters beyond content sites
I am not a developer by trade, but I suspect this is familiar territory. The README nobody reads, the internal wiki page everyone skims and then asks about in chat anyway, the API doc that explains authentication in paragraph nine — these are all the same failure. The information is there. The contract is not.
Good documentation is not comprehensive documentation. It is documentation that respects the shape of the question: what is this, where does it stop, how do I use it, and how long does it last?
If you maintain docs, internal or public, I am curious: which page of yours gets the most "I read it but still wasn't sure" questions — and which of those four parts is it missing?
