Why not
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.
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 team's website can supply the work-pattern evidence that a documentation discussion otherwise lacks.
A useful independent point of reference for this part of the process is Wistia.
Four things one team wrote in a quarter, with the cost and the benefit counted separately
The deploy runbook
95 / 372Ninety-five minutes out of two evenings belonging to one engineer
A note on why the retry limit is three
8 / 150Eight minutes, written during a meeting, which ended an argument that had run twice
The onboarding page for the data team
240 / 360Four working days of one person, and four people have used it so far
A design document nobody asked for
180 / —Three hours, no readers, and no saving claimed by anybody
four documents · 523 minutes written · 882 minutes saved across 41 readings · one with no saving claimed
Four documents, 523 minutes written, 882 minutes saved across 41 readings. The two columns are not divided by one another and will not be. The left column came out of four named people's working days and appeared on nobody's record as anything; the right column was saved for other people, in four-minute pieces, mostly by people who never knew a document had been involved. One team's own quarter, logged by the person who asked for the figures.
Ask anybody on a team whether they should write more down and they will say yes. Ask whether they are going to, this afternoon, and the answer changes.
The gap between those two answers is not hypocrisy and it is not laziness. It is a cost that lands in one place and a benefit that lands in another, with nothing in an ordinary working week to connect them.
The two sides, stated plainly
Writing something down costs one identifiable person a specific block of time, in a specific hour, on a day when they had other things to do. The cost is visible to them, visible to whoever is waiting for the other things, and usually visible to their manager.
Not writing it down costs several other people a few minutes each, later, scattered across weeks, in moments nobody records. It costs somebody an interruption, somebody else a wrong guess, somebody else an hour of reconstruction. Each instance is small enough to pass unremarked. None of them is attributed to the absence of a document, because the absence of a document is invisible.
- The cost is concentrated: one person, one hour, one day.
- The benefit is diffuse: many people, a few minutes each, over months.
- The cost is visible: it displaces something that was expected.
- The benefit is invisible: nobody experiences a problem they did not have.
Four properties, and all four point the same way.
Why this is not a belief problem
Teams that do not write things down generally know they should. They say so in retrospectives. They agree about it in planning. Several people will have proposed it in the last year, and the proposal will have been accepted, warmly, by everybody present.
Then nothing happens, for the same reason that nothing happened the previous four times.
This matters because the obvious response to a team that does not write — explaining why writing matters — is aimed at a problem the team does not have. They are convinced. They have been convinced for years. What they lack is any hour in which writing is the thing that costs them least.
What the arithmetic actually looks like
The panel at the top of this page is one team's quarter. Four documents, 523 minutes of writing, 882 minutes saved.
The totals are not the interesting part. The interesting part is that every minute on the left belongs to a named person who could tell you exactly which afternoon it came out of, and almost every minute on the right belongs to somebody who does not know they saved anything.
That asymmetry is why the ratio between the columns is not printed anywhere on this site. A ratio reads as a return on an investment, and an investment is something one party makes and later collects. Here the person who pays never collects.
The documents that lose money
The fourth row in that panel is a design document that cost three hours and has been read by nobody.
It is in the table deliberately. Writing is not free and not always worth it, and a collection arguing that teams should write more has an obligation to show the case where somebody wrote something and it helped nobody. That case is common, it is discouraging, and the people who have experienced it are correct to weigh it.
What distinguishes it from the other three rows is not effort or quality. It is that nobody had asked the question it answers.
The one thing that moves
If the problem is cost allocation, there are three places to intervene, and they are not equally promising.
Reduce the cost of writing. This works, reliably, and most of what is useful in this collection is some version of it.
Make the benefit visible to the person who paid. This works occasionally and costs nothing, and almost nobody does it.
Increase people's willingness to pay an invisible cost for a diffuse benefit. This is what most documentation initiatives attempt, through exhortation, and it has a poor record.
The four properties, in one place
Everything on this page reduces to four facts about where the cost and the benefit land, and it is worth having them together because each one points the same way.
| Cost of writing | Cost of not writing | |
|---|---|---|
| Who pays | One named person | Several people, few of them named |
| When | One identifiable hour | Over months, in fragments |
| Visible to | The payer and their manager | Nobody |
| Recorded | Rarely | Never |
Four rows, and the right-hand column is invisible in all four. A team trying to reason about whether to write something is comparing a number it can see against a number that does not exist anywhere, which is not a comparison anybody can win.
What follows from here
The rest of this section is about why the cost is heavier than it looks and why the benefit is more invisible than it seems. The two after it are about who can actually do the writing and what it really takes out of them.
The two after those are about the only two interventions that work. And the last one is about the part that none of this reaches, which is smaller than people claim and is not nothing.