What it costs
The Liability You Take On by Publishing
Publishing a page creates an open-ended obligation to keep it true, and people who have been blamed for a stale document price that obligation correctly.
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
Which client agreed to the export
Reconstructed from mailbox searches
Twice by people not on the thread
two things nobody wrote down · 10 occasions it cost somebody something
Two things, ten occasions, and nobody billed any of it to anybody.
Before adding another required page, managers can the current overview and check whether the underlying bottleneck is missing knowledge, overloaded authors, or unclear ownership.
For additional context beyond this collection, see the resources maintained by Google Skillshop.
Four things left unwritten by people who had explicitly considered writing them
How the pricing tiers are calculated
Explained individually, three times
The author said a page would need updating every time pricing changed
The deployment checklist
Kept in one person's notes
They had written one before and been blamed when it went stale
What each environment is for
Asked and answered in chat
The author expected the environments to be reorganised within months
The support escalation path
Asked in the support channel
Nobody wanted to be the person who had defined it wrongly
four things nobody wrote down · 15 occasions it cost somebody something
Four things, fifteen occasions. None of these authors was short of time and none thought documentation was unimportant. Each had weighed the ongoing obligation a published page creates and decided against taking it on. That is a real cost and is almost never counted. One team's own quarter.
Writing something down is usually discussed as a one-off cost: the time it takes to write. It is not a one-off.
A published page is a standing claim about the world, attached to a name, which will still be there when the world changes. People who have been on the wrong end of that once price it accordingly.
What the obligation actually is
Three distinct burdens, and they arrive at different times.
Keeping it true. The page describes something that will change, and somebody has to notice and amend it.
Being asked about it. A page with your name on it makes you the person people come to, which can mean more interruptions rather than fewer.
Being held to it. If somebody follows the page and it goes wrong, the page is the artefact everybody looks at, and the author is the person attached to it.
Why the third one dominates
The first two are manageable. The third is the one that stops people, and it is almost never acknowledged in conversations about documentation culture.
A stale page is treated, in most teams, as worse than no page — rightly, because it produces confident wrong action. The person who wrote it two years ago and has since moved to another team is the person named at the top.
Anybody who has experienced that once will think carefully before publishing the next thing, and they are not being precious.
The response that makes it worse
Telling people that a stale page is better than nothing.
It is sometimes true and it is not reassuring, because the thing being feared is not a philosophical judgement about staleness. It is a specific future conversation in which somebody says "the runbook said to do that" and the author has to explain themselves.
What addresses the fear is not an argument. It is a change in what a page is understood to claim.
Writing the claim down
The repair is one line at the top of the page, and it costs nothing:
Written on 14 March by [name], describing how this worked then. Not maintained. If it is wrong, it is wrong — correct it or ask in the channel.
That line does three things. It time-stamps the claim, so a reader can judge it. It states the maintenance commitment honestly, which is usually none. And it invites correction rather than complaint.
A team where this line is normal has removed most of the liability, because the page no longer claims to be current and nobody can be blamed for its having aged.
Two kinds of page
The distinction worth making explicit:
Dated records. What happened, what was decided, how it worked in March. These never go stale, because they were always about a moment. An incident write-up from last year is not out of date; it is history.
Live descriptions. How the thing works now. These require maintenance and should have an owner, and there should be few of them.
Most of what teams fail to write is in the first category and is being priced as though it were in the second. Framing a page as a record rather than a description removes the obligation entirely, and loses very little.
Who should own the live ones
Somebody, named, and the name should be a role rather than a person where possible.
The common failure is a live description whose owner left eighteen months ago, which combines every bad property: it claims to be current, nobody maintains it, and the name on it belongs to somebody who cannot be asked.
Where no owner can be found, the honest move is to demote the page from description to record by adding a date and a note saying it is unmaintained. That takes thirty seconds and converts a liability into an asset.
Two kinds of page, and which obligation each carries
Most of the liability people fear attaches to one of these and not the other, and separating them removes it from about three-quarters of what a team writes.
| Dated record | Live description | |
|---|---|---|
| Claims | How it was then | How it is now |
| Goes stale | No — it was always about a moment | Yes |
| Needs an owner | No | Yes |
| Example | An incident write-up, a decision note | A runbook, a current process |
The useful move is to write records by default and promote something to a live description only when it genuinely must be current. A record costs nothing to keep and cannot be held against its author.
The cost that remains
None of this removes the obligation entirely for genuinely live documentation, and some documentation genuinely has to be live.
What it does is stop the obligation attaching to everything by default, which is the state most teams are in and which prices every page as though it were a permanent commitment. Separating the two kinds is the difference between a team that writes records freely and one that writes nothing because everything feels like a promise.