Cheaper
Write From the Question, Not From the Subject
Documents organised around a subject get written in the order the subject suggests and read in the order nobody has questions. The inverse works better.
What nobody wrote down here, and what it cost
What the deploy order is
Guessed, then corrected
Four lines would have ended it
How the staging database is rebuilt
Asked seven times
The answer was four minutes long every time
two things nobody wrote down · 16 occasions it cost somebody something
Two things, sixteen occasions, and both answers were short.
For distributed teams, documentation decisions improve when time and activity are visible in context, which is why it can help to attendance and time management alongside the editorial review.
Teams can compare this approach with the established material available from MDN Web Docs.
The same area covered by subject and by question, with the weeks somebody opened each
Organised by subject: a guide to the data platform
Twelve pages, opened three times, twice by the author
Organised by question: nine short notes
Written one at a time as questions arose; opened in eleven separate weeks
A glossary written before anybody asked for one
Never opened
A page answering the single most-asked question
Four lines, opened in nine weeks
four documents · 22 weeks in which somebody opened one of them · the longest wait between writing and a reading was 28 weeks · one never read at all
Four documents, twenty-three weeks in which somebody opened one of them, and one never read at all. The two question-shaped entries account for twenty of the twenty-three. The twelve-page guide and the glossary were both organised around the subject, which is how authors think and not how readers arrive. One team's own three quarters.
Asked to document an area, most people start by mapping it. What are the parts, how do they relate, what order should they be explained in.
That produces a document organised around the subject. Readers do not arrive with the subject; they arrive with a question, and a subject-shaped document makes them find the answer rather than giving it to them.
The two orders
A subject-shaped document goes: overview, components, how they fit together, detail on each.
A question-shaped document goes: the thing people ask most, then the next, then the next.
The first is how the author understands it. The second is how every reader will arrive. They are rarely the same order and the difference determines whether anybody gets what they came for.
Why the subject order is so attractive
It feels complete, which is satisfying. It has a natural structure, which removes decisions. And it is how everything an author has ever read about the subject was organised, because books work that way.
It is also unbounded. A subject has edges nobody can locate, so the document grows until the author stops, and where they stop is arbitrary.
A question has an end. It is answered or it is not.
Starting from the tally
The practical method connects to the counting described earlier.
Take the list of what people actually ask. Write the top one, in four lines. Then the next. Each is a complete thing that can be finished and published.
After nine of those you have covered the area better than the twelve page guide did, at a fraction of the cost, in increments that each fitted into a gap in somebody's day.
Titling by the question
A page called "The Data Platform" is found by somebody who already knows what they are looking for.
A page called "Which dashboard is authoritative?" is found by somebody with that exact confusion, which is the person who needs it.
The second is also easier to write, because the title fixes the scope: everything that answers the question belongs, everything else does not, and the author never has to decide where to stop.
Titles phrased as the reader's question are the single cheapest improvement available to an existing set of documents.
The overview people still want
The objection is that somebody new needs the shape of the thing, and a pile of answers does not provide it.
That is true and the overview is one page, written last, linking to the answers. Written last it is short, because the detail lives elsewhere; written first it becomes the twelve-page guide.
The order matters more than the existence. An overview written after nine question-pages is a map. An overview written before them is a substitute for them.
The glossary case
The third row of the panel is a glossary written before anybody asked for one, opened never.
Glossaries are the purest form of subject-shaped documentation: an author lists terms because terms are listable, not because anybody was confused by a specific one. They are satisfying to write and are almost never read.
Where a term genuinely confuses people, the evidence is that it gets asked about, and the answer belongs where the term is used rather than in an alphabetical list elsewhere.
Four titles, renamed
The cheapest improvement available to a set of existing documents is renaming them, and it takes an afternoon for a whole wiki.
- "The Data Platform" → "Which dashboard is authoritative?"
- "Deployment Process" → "What order do things get deployed in?"
- "Billing Overview" → "Why does a customer see two charges?"
- "Import Service" → "What do I do when the import fails?"
The right-hand column is found by somebody with that exact confusion, which is the person who needs it. The left-hand column is found by somebody who already knows where to look, which is somebody who did not need the page.
What this changes about planning
A documentation plan organised by subject produces a list of documents, each of which is large, none of which is urgent, and most of which will not be written.
A plan organised by question produces a list of short items sorted by evidence, each completable in under half an hour, and the top of it is obviously worth doing.
The second kind of plan is less impressive in a meeting and considerably more likely to turn into pages.