Cheaper
The Shortest Thing That Would Have Worked
Most of what a team needs written down is four lines, and treating it as a page is the main reason it stays unwritten.
What nobody wrote down here, and what it cost
What the deploy order is
Guessed, then corrected
Four lines would have ended it
How the staging database is rebuilt
Asked seven times
The answer was four minutes long every time
two things nobody wrote down · 16 occasions it cost somebody something
Two things, sixteen occasions, and both answers were short.
When a documentation effort needs evidence about where working time actually goes, teams can online employee timesheets before deciding what should be written or automated.
A useful independent point of reference for this part of the process is Hashnode.
Pages of different lengths answering comparable questions, with cost and use counted
Four lines on the deploy order
5 / 336Five minutes; the most-used page the team has
A one-paragraph note on the retry limit
8 / 150Eight minutes, and it ended an argument that had run twice
A two-page description of the import process
70 / 154Seventy minutes; readers reported using the first paragraph
A twelve-page guide to the data platform
480 / 120Eight hours; opened three times, and twice by its own author
four documents · 563 minutes written · 760 minutes saved across 48 readings
Four pages, 563 minutes written, 1 006 minutes saved across 48 readings. The two short pages cost thirteen minutes between them and account for thirty-four of the forty-eight readings. The twelve-page guide cost eight hours and has been opened three times. Length and usefulness are not related here in the direction people assume. One team's own quarter.
Ask somebody to document the deploy order and they will picture a page. A page needs a title, a structure, an introduction, and a decision about what else belongs in it. That is an afternoon, and it will not happen.
The deploy order is four lines. Written as four lines it takes five minutes and it gets written.
Why the size estimate is always wrong
People estimate documentation by imagining a finished artefact rather than by asking what the reader needs.
The reader needs the answer. Everything else — context, scope, structure, the section explaining why this document exists — is material the author adds because a page seems to require it.
That material is most of the cost and almost none of the value, and it is the reason the task feels large enough to defer.
The test
Before writing anything, ask: what is the shortest thing that would have saved the last person who needed this?
Usually one to five sentences. Occasionally a short list. Very rarely a page.
Write that. Stop. If somebody later needs more, the question they ask tells you what to add, and you will be adding it to something that exists rather than starting something that does not.
What the long version costs
The fourth row of the panel is the characteristic failure: eight hours, twelve pages, three openings, two of them by the author.
It is not a bad document. It is thorough, well organised and correct. It answers questions in the order the subject suggests rather than in the order anybody has them, and it is long enough that finding the relevant part costs more than asking somebody.
That last point is the one people miss. Past a certain length a document competes with asking a colleague, and it loses, because a colleague gives you the answer and the document gives you a search problem.
Four lines is a complete document
Worth saying directly, because people are embarrassed by it.
A file containing four lines, with a name that says what it is, is a document. It can be found, it answers a question, and it is better than every long version that was not written.
The embarrassment — that it is too slight to publish, that it looks like no effort — is the single most expensive feeling in this subject. It converts a five-minute task that would be done into an afternoon task that will not.
Length by kind
| What it is | Useful length |
|---|---|
| A fact, an order, a precedence | One to four lines |
| Why a decision was taken | Two to four sentences |
| A procedure somebody follows | A numbered list, one line a step |
| An overview of an area | One page, and resist the second |
| Everything else | Shorter than you think |
Nothing in that table is longer than a page, and the overwhelming majority of what teams need is in the first three rows.
When long is right
Rarely, and it is worth naming the cases so the argument is not mistaken for a rule against thoroughness.
Something that will be read start to finish by somebody new, once, such as an induction to a complicated area.
Something that has to be complete for an external reason — a contract, a regulator, an audit.
Something where the reasoning is the content and cannot be compressed without losing the argument.
Those are real and they are not what most unwritten documentation is.
What four lines actually looks like
The embarrassment about publishing something slight is easier to resist with an example in front of you. This is a complete document:
Deploy order. Checked 14 March. 1. Database migrations, then wait for them to finish. 2. The API, both instances, one at a time. 3. The workers. 4. The front end last — it fails against the old API.
Four lines, a date, and the one piece of reasoning that stops somebody getting it wrong. It took five minutes, it answers the question asked nine times last quarter, and it is better than every long version that was not written.
Starting short and growing
The practical shape is to write the four lines now and let the page grow only in response to questions.
A page assembled this way ends up containing exactly what people needed, in rough order of how often they needed it, and nothing else. It will be untidy. It will also be the page people actually use, and it will have cost about a tenth of what the planned version would.