Cheaper
Making the writing cheap enough to happen
Almost everything that works here reduces the price of the act rather than increasing anybody's willingness to pay it.
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.
Put the Answer Where the Question Was Asked
The cheapest documentation moment is the one where somebody has just asked, because the answer is already composed and only needs putting somewhere that lasts.
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.
Templates, and the Ones That Make It Worse
A template with two or three fields makes writing cheaper by removing a decision. A template with eleven sections makes it dearer by adding ten.
Write From the Question, Not From the Subject
Documents organised around a subject get written in the order the subject suggests and read in the order nobody has questions. The inverse works better.
Stopping at Good Enough to Be Useful
Most of the cost of a page is incurred after it was already useful, and the extra buys very little that any reader notices.
Dictating, Pasting and Screenshotting
Prose written from memory is the slowest and least accurate way to document something, and three cheaper methods are available to anybody.
Letting the First Version Be a Bad Version
A rough page published today is worth more than a good page published in six weeks, and it gets better for free once people start using it.
One Page, Not a System
Teams that decide to document build the container first. It is the easy part, nobody reads it, and the energy runs out before any answers get written.
What Not to Write at All
Some things should not be documented, and knowing which is as valuable as knowing what to write, because a wasted page costs twice.