Why not
Writing Exposes How Much You Had Not Worked Out
Explaining something in writing reveals which parts you only half understand, and that discovery is more expensive than the typing.
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
What the deploy order is
Guessed, then corrected by whoever noticed
Wrong on the ninth occasion
Why the retry limit is three
Re-argued at two planning meetings
The reasoning was in nobody's head
three things nobody wrote down · 20 occasions it cost somebody something
Three things, twenty occasions, and one customer who noticed.
Where the real question is capacity rather than willingness, the website can supply the work-pattern evidence that a documentation discussion otherwise lacks.
Teams can compare this approach with the established material available from Later.
Five things one team did not write down, with the reason the author gave when asked later
Why the import runs twice
Asked at every incident for a year
The person who knew said they would have had to work out the real reason first
How the pricing tiers were decided
Reconstructed from a spreadsheet
The original reasoning turned out to be three separate decisions, not one
What the on-call rota actually covers
Guessed, then corrected
Writing it required settling a question nobody had settled
The architecture, in one page
Attempted twice and abandoned
Both drafts described the result and stopped where the reasons began
Why we use the nightly job
Re-argued in two planning meetings
The answer was known and nobody could state it in a sentence
five things nobody wrote down · 16 occasions it cost somebody something
Five things nobody wrote, sixteen occasions they cost somebody something. In four of the five, the obstacle named afterwards was not time. It was that writing the thing down would have required working something out that had never been worked out. One team's own quarter, collected afterwards by asking the people who had not written.
Explaining something out loud is forgiving. You can gesture, you can say "roughly", you can stop at the point where the other person nods.
Writing the same explanation is not forgiving. A sentence either says something or it does not, and the parts you have never properly worked out announce themselves in the first draft.
What actually stops the writing
The typing is not the hard part and almost never was. The hard part is the moment, usually four sentences in, where you discover that the reason you are about to give is not the reason, or is one of three reasons, or is a thing you have believed for two years without examination.
At that point the task has changed. It was going to be twenty minutes of writing down something known. It has become an unbounded piece of thinking, with an unclear end, undertaken at four in the afternoon for the benefit of nobody in particular.
Most people stop. The page does not get written, the reason gets recorded as "no time", and both the author and everybody around them believe that.
The specific places it happens
Reasons. Writing what a thing does is easy. Writing why it is that way reliably turns out to require an archaeology nobody has done.
Boundaries. "What this covers" forces a decision about what it does not cover, which is frequently a decision the team has avoided making for years because avoiding it has been cheaper than settling it.
Ownership. Writing down who decides something requires knowing, and several of the things a team does are things nobody has ever been named for.
Exceptions. Any honest description of a process runs into "except when", and the exceptions are the part that lives only in habit.
Why this is a good sign and still a real obstacle
The discovery is valuable. A team that finds out, while writing, that three people hold different views about what the on-call rota covers has learned something worth more than the page.
It is also genuinely expensive, and pretending otherwise is why so much advice about documentation does not connect. Telling somebody that writing clarifies thinking is true and is heard, correctly, as "this task is larger than you estimated".
The reason it is not written down is not that nobody has the time. It is that writing it down requires somebody to decide a thing that everybody has found it cheaper not to decide.
What to do with the discovery
Three options, and the usual choice is the fourth, which is to abandon the page.
Write what you know and mark the hole. A sentence reading "this runs twice daily; the original reason is not recorded and nobody currently knows it" is a useful document. It is more useful than the absence, and it is honest about its own limits.
Split the page from the question. Publish the description now; raise the unresolved thing separately, as what it is — a decision somebody needs to make rather than a gap in a document.
Take the question to whoever can settle it, with the half-written page as the evidence that it needs settling. A draft that stops at "except when" is the clearest argument that the exception needs a name.
Marking holes instead of filling them
The habit worth building is making an unknown explicit rather than quietly routing around it.
Routing around is the default. People write the parts they are sure of and leave out the parts they are not, which produces a document that looks complete and is wrong by omission — and that is the document somebody will act on in six months.
A page with three sentences and two stated gaps is better than a page with three sentences and two silences, and it costs the same.
Marking a hole, in practice
A page with stated gaps is a usable page, and the stating takes one line. The forms that work are short and specific.
- "This runs twice daily. The original reason is not recorded and nobody currently knows it."
- "Covers the first three steps. The rest is not written."
- "Two people disagree about what this covers; see the thread."
- "Accurate for the production environment. Staging may differ and has not been checked."
Each of those is more useful than silence in the same place, and each takes about fifteen seconds. The reader learns what they are holding, and the author has made a complete statement rather than an incomplete one.
The alternative — writing the parts you are sure of and saying nothing about the rest — produces a page that looks finished and is wrong by omission.
The thing not to say
The one response that makes this worse is telling somebody that writing it up will help them understand it better.
It is true. It is also an argument for spending more time on something they were already reluctant to start, offered by a person who is not going to be doing it.