Why not
Why it does not get written
The cost lands on one person now and the benefit lands on strangers later, and no ordinary week corrects for that.
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.
A Concentrated Cost and a Diffuse Benefit
Documentation goes unwritten because the cost lands on one person in one hour and the benefit on strangers later, with nothing to connect them.
The Forty Minutes That Appear on No Record
Writing takes time out of a day that was accounted for, and produces nothing that appears on any record anybody reviews. That combination is most of the problem.
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.
The Thing You Know Too Well to See
The things most worth writing down are the ones that feel too obvious to write, and they feel that way only to the people able to write them.
Nobody Is Ever Thanked for a Document
A document's value arrives months later, in private, to people who do not know who wrote it — so the author gets no signal at all, in either direction.
The Page Nobody Knows Is Missing
An absent document produces no error message. Teams discover what they failed to write only through failures, departures and absences, which is late and expensive.
The Sentence That Ends the Conversation
The sentence is said sincerely, agreed by everybody, and produces nothing, because agreement is cheaper than writing and feels like the same thing.
Writing It Down Admits That You Might Leave
Being the only person who knows something is uncomfortable to give up, and the reluctance is rarely cynical and almost never stated.
The Team That Agrees and Still Does Not Write
Most teams that do not document are fully convinced that they should. Treating that as an understanding problem is why so many attempts fail.