Cheaper
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.
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.
A useful operational baseline is to compare the writing burden with real work patterns; workforce productivity analytics shows one practical way to make that comparison without relying on memory.
For additional context beyond this collection, see the resources maintained by Stack Overflow.
Four pages one team decided afterwards it should not have written
A glossary of internal terms
90 / 5Ninety minutes; opened once, by its author, checking a spelling
A page describing something due to be replaced
120 / 20Replaced four weeks later; the page was deleted unread
A page duplicating the vendor's own documentation
75 / 18The vendor's version was better and was updated when theirs changed
A page restating what the code already says
60 / 16Went out of date with the first change and was wrong for five months
four documents · 345 minutes written · 59 minutes saved across 10 readings
Four pages, 345 minutes written, 71 minutes saved across ten readings. This is the only panel on this site where the right-hand column is smaller than the left, and it is here on purpose: a collection arguing for more writing has to show the cases where writing lost. One team's own quarter.
A collection arguing that teams should write more has an obligation to say where writing is a waste. Otherwise it is advocacy, and advocacy is what everybody has already had.
Some pages lose. They cost the author's time and then cost the reader's time by being there.
Things about to change
A page describing something that will be replaced in a month is written, read twice, and deleted.
Worse, it may not be deleted, in which case it describes a thing that no longer exists and misleads somebody in eight months.
The test is whether the subject is expected to survive long enough to be asked about several times. Where the answer is no, write the four lines somebody needs today, in chat, and let it go.
Things somebody else maintains better
Vendor documentation, library documentation, the manual for a tool.
Restating these produces a worse copy that goes stale when the real one is updated, and the real one is updated by people who are paid to do it.
What is worth writing is the part specific to your team: which settings you use and why, what you had to work around, what bit you when you adopted it. That is three lines and a link, and it is material nobody else has.
Things the artefact already says
A page listing what the configuration options are, when the configuration file lists them. A page describing what a function does, when the function says.
This is the clearest case and the most commonly committed, because it is easy to write and feels thorough. It is a copy that will diverge, and when it diverges the copy is wrong and somebody will believe it.
What is worth writing is what the artefact cannot say: why it is that way, what was tried first, what must not be changed.
Things nobody has asked about
The hardest one to accept, because it feels like an argument against foresight.
A page written in anticipation of a question nobody has had is a bet, and on the evidence in this collection most such bets lose — the twelve-page guide, the glossary, the design document on the home page of this site.
The exception is departure risk: something that will be lost when a person leaves is worth writing before anybody asks, because the asking will come after the opportunity has gone.
So: write what is asked, plus what would be lost. Not what might be asked.
Things that would be better fixed
Where a page exists to explain a confusing thing, the page is sometimes a way of not fixing the thing.
A document explaining which of two dashboards is authoritative is useful today and is also an argument for deleting one of them. A runbook with eleven manual steps is a candidate for a script.
Writing it down is not wrong in these cases, and it should be accompanied by somebody noticing that the underlying problem is now documented rather than solved.
The test, in one line
Will somebody with a question find this, and will it answer them, and will it still be true then?
Three conditions, and a page failing any of them is a page costing more than it returns. Most of the losing pages above fail the third.
The three questions before writing
Thirty seconds, and a no to any of them means the page will cost more than it returns.
- Will somebody with a question find this?
- Will it answer them?
- Will it still be true then?
Most of the losing pages fail the third. A description of something due to be replaced, a copy of a vendor's manual, a restatement of what the code says — all of them are true on the day and false within months, and the false version is the one somebody will find.
The glossary and the unasked-for overview fail the first two, which is a different failure with the same outcome.
What to do with the ones already written
Delete them, or date them.
Deleting is better and is socially hard, because somebody wrote it. The compromise is a line at the top saying what it described and when, which converts a misleading live description into a harmless dated record.
A team that does this to a dozen stale pages in an afternoon usually finds the remainder become noticeably more trusted, which is a return on half a day of deleting.