What it costs
Count the Asks Before Deciding What to Write
A documentation backlog built from what gets asked is short, surprising and correct. One built from intuition is long, tidy and mostly unread.
What nobody wrote down here, and what it cost
How the staging database is rebuilt
Asked of the same person seven times
Four minutes each, plus the interruption
Which client agreed to the export
Reconstructed from mailbox searches
Twice by people not on the thread
two things nobody wrote down · 10 occasions it cost somebody something
Two things, ten occasions, and nobody billed any of it to anybody.
A useful operational baseline is to compare the writing burden with real work patterns; this product page shows one practical way to make that comparison without relying on memory.
The broader workflow can also be checked against guidance from LinkedIn Business.
One engineer's tally, kept for a quarter, sorted by how often each thing was asked
What the deploy order is
Asked or corrected
Nine, and the engineer had not thought of this as a documentation gap
How the staging database is rebuilt
Asked of them directly
Seven, which they had expected to be about two
Which dashboard is authoritative
Asked in the support channel
Seven, from five different people
What the legacy export is for
Routed to them automatically
Six, and they had assumed nobody cared about it
Why the import runs twice
Asked at incidents
Three, and this was the one they would have written first
five things nobody wrote down · 32 occasions it cost somebody something
Five questions, thirty-two occasions. The engineer's own guess, made before the tally and written down for comparison, put the import question at the top and did not include the deploy order at all. The tally and the intuition disagreed about four of the five. One engineer's own quarter.
Deciding what to document by thinking about it produces a list organised around the shape of the systems: a page for each service, a page for each process, a glossary.
Deciding by counting what people ask produces a different list. It is shorter, it is untidy, and it is right.
The method
A file. One line each time somebody asks you something you have answered before. Date, question, who asked.
Nothing else. No categories, no tool, no agreement from anybody.
After a month, sort by frequency. The top five are the backlog.
Why it beats intuition
The panel above is one engineer's tally against their own prediction, written down in advance, and they disagreed about four items out of five.
The reason is that memory of being asked is unreliable in a specific direction. Questions that are interesting are remembered; questions that are trivial and frequent are not, because each instance is forgotten within the hour.
The trivial frequent ones are precisely the ones worth a page, because they are cheap to write and are costing the most in aggregate.
What the tally tends to surface
Ordering and precedence. What must happen before what, which thing is authoritative, what the current state of something is.
Things nobody considers documentation. The deploy order is not a system or a process; it is a fact, it fits in four lines, and it does not occur to anybody as a candidate for a page.
Things the person being asked considers too obvious. Covered earlier in this collection, and the tally is the mechanism that makes them visible, because frequency is observable where obviousness is not.
What it does not surface
The deep things. Why the architecture is the shape it is, what the reasoning behind a decision was, how the billing reconciliation actually works.
These are asked rarely and matter enormously, and a frequency-sorted list will put them at the bottom.
So the tally is one input, not the whole backlog. The other input is the departure risk: what would be lost if a particular person left. Those two lists overlap very little and both are short.
Keeping it for a month, not a week
A week is not long enough. The recurrence interval for most of these is ten days to three weeks, so a week-long tally shows each question once and sorts nothing.
A month is the minimum. A quarter is better and is hard to sustain.
The practical compromise is to run it for a month twice a year, which takes no discipline between times and produces most of the value.
Doing it as a team
The individual version works and the team version is better, because the same question asked of three different people shows up three times.
The lightweight form is a shared file or channel where people drop the question when they notice they have answered it before. No process, no owner, no review.
It works in teams where somebody keeps nudging it along for the first month and dies in teams where nobody does, which is true of everything in this collection.
What to do with the top of the list
Write four lines. Not a page, not a section, not a structure.
The top items on a frequency list are almost always short answers, and writing them as short answers is what makes them get written at all. The next section of this collection is about keeping them short.
Then cross them off the tally and keep counting, because the list regenerates and the second month's list is different from the first.
What a month of tallying tends to produce
The list is consistently different from what anybody predicts, and the differences fall into a pattern worth expecting.
| At the top, usually | At the bottom, usually |
|---|---|
| Ordering and precedence | How a system works internally |
| Which of two things is current | Why a decision was taken |
| Short facts nobody thinks of as documentation | Anything anybody planned to write |
| Things the expert finds too obvious | Things the expert finds interesting |
The right-hand column is not unimportant — the bottom two rows are exactly what gets lost when somebody leaves. It is simply not what a frequency count measures, which is why the tally is one input and not the whole backlog.
The thing the tally changes most
Not what gets written — though that too.
It changes the conversation about whether writing is worth it, from an exchange of opinions into an argument about a specific list of specific recurrences. That conversation has an answer, which is a considerable improvement on the one most teams have been having for several years.