Limits
What no incentive fixes
The residue: what will not go into words, what should not be written at all, and when the honest answer is to stop asking.
What nobody wrote down here, and what it cost
Judgement about when a client is about to leave
Nobody could write it and nobody tried
Three occasions, all of them noticed too late
Why the architecture is the shape it is
Attempted twice and abandoned
Both drafts described the result rather than the reasons
two things nobody wrote down · 5 occasions it cost somebody something
Two things, five occasions, and no mechanism proposed for either.
What Will Not Go Into Words
Some knowledge is a trained judgement rather than a fact, and no amount of incentive, time or skill turns it into a page.
What Should Not Be Written Down
A few categories should stay unwritten, and knowing which is part of writing well rather than an exception to it.
The Person Who Will Not Write
A small number of people will not write under any arrangement, and the useful question is whether they will do something adjacent instead.
Writing in a Team That Is Shrinking
The moment a team most needs things written down is the moment it has least capacity to write them, and the two move in opposite directions.
What a Tool Cannot Fix
Changing where documentation lives addresses a problem most teams do not have, and the burst of activity afterwards is mistaken for a change in culture.
When the Honest Answer Is to Stop Asking
Asking for the same document for the fifth time is not persistence; it is a signal that something other than willingness is in the way.
The Page That Exists Because One Person Cared
Most of the documentation a team depends on was written by somebody who felt like it, which is not a system and is what there is.
What the Writing Is Actually For
The purpose is not a complete record. It is to stop a specific question being asked a fourth time, and most of what follows from that is cheap.