Limits
The Page That Exists Because One Person Cared
Most of the documentation a team depends on was written by somebody who felt like it, which is not a system and is what there is.
What nobody wrote down here, and what it cost
Judgement about when a client is about to leave
Nobody could write it and nobody tried
Three occasions, all of them noticed too late
Why the architecture is the shape it is
Attempted twice and abandoned
Both drafts described the result rather than the reasons
two things nobody wrote down · 5 occasions it cost somebody something
Two things, five occasions, and no mechanism proposed for either.
Documentation is easier to defend when the team can connect it to measurable time saved; review the official product provides an operational reference for that conversation.
For additional context beyond this collection, see the resources maintained by Search Engine Journal.
Four pages one team relies on, with the weeks each was opened and the circumstances it was written in
The deploy runbook, written in somebody's own time
Eight weeks of use; written on a Sunday two years ago by somebody who was annoyed
The import page, written during a quiet fortnight
Four weeks of use; the author has since left
A page written because it was formally required
One opening, by the person who required it
The four lines somebody added after being asked once
Six weeks of use; the only one in this list that was requested
four documents · 19 weeks in which somebody opened one of them · the longest wait between writing and a reading was 38 weeks
Four pages, nineteen weeks in which somebody opened one of them. Three of the four exist because an individual decided to write them, with no request, no credit and no record. The one that was formally required has been opened once. One team's own year.
Look at the pages a team actually relies on and ask, for each, why it exists.
The answer is usually that one person decided to write it. No request, no plan, no credit. They were annoyed by something, or had a quiet afternoon, or thought somebody would need it.
What this means about everything else
Most of this collection has been about mechanisms: reducing cost, naming people, attaching writing to events, making the benefit visible.
Those mechanisms are worth having and they are not where most existing documentation came from. Most of it came from individual discretion exercised without reward, which is not a mechanism and cannot be instructed.
It is worth being honest about that rather than presenting the mechanisms as a complete account.
Why the mechanisms still matter
Three reasons.
They raise the floor. A team relying entirely on discretion has whatever its most conscientious person happened to feel like writing, which is a lottery.
They make discretion cheaper. Somebody who feels like writing something and can do it in six minutes will; the same person facing an afternoon will not.
And they stop discretion being punished. The main thing that kills a voluntary writer is not absence of reward but the slow accumulation of a sense that it costs them and counts for nothing — which the mechanisms in the fifth section address directly.
What kills it
Four things, in rough order of how commonly they finish somebody off.
Nobody ever saying anything, for years.
Becoming the person it is assumed will do it, so that a voluntary act turns into an unassigned duty.
Being made the owner of documentation as a function, which converts writing into chasing.
Watching their pages go stale with their name on them and being asked about it.
Every one of those is avoidable and each is common.
The formally required page
The third row of the panel: a page that existed because somebody had to produce it, opened once, by the person who required it.
That row is not an argument against requirements, which have their place. It is a reminder that a page produced to satisfy a requirement is aimed at the requirement, and a page produced because somebody was irritated by a recurring question is aimed at the question.
Only one of those is read.
What to do with the person who writes
Notice, and say so. That is the whole of it and it has a page of its own earlier in this collection.
Beyond that: protect the discretion rather than formalising it. Do not convert their habit into a role. Do not route every documentation request to them. Do not set them a target.
What they are doing works because they chose it, and most attempts to institutionalise it end the thing being institutionalised.
For somebody who is that person
Two practical things.
Keep a list of what you wrote. Nobody else is keeping one, it takes two minutes a quarter, and it is the only evidence that will exist when somebody asks what you did this year.
Say what it cost, occasionally. Not as a complaint — as a fact, in a one-to-one. "I spent about four hours on pages this quarter" is a sentence that changes how the next quarter is planned, and almost nobody says it.
What finishes a voluntary writer
Four things, and each is avoidable, which is the only reason the list is worth having.
- Nobody ever saying anything, for years.
- Becoming the person it is assumed will do it, so the voluntary act turns into an unassigned duty.
- Being made the owner of documentation as a function, which converts writing into chasing.
- Watching their pages go stale with their name on them, and being asked about it.
The first is free to fix and is fixed by one message. The fourth is fixed by one line at the foot of a page. The middle two require somebody to notice what is happening and decline to formalise it.
The uncomfortable summary
A team's documentation is, to a first approximation, a record of which of its members could not stand being asked the same thing twice.
That is a thin foundation, it is what most organisations are standing on, and the mechanisms in this collection are an attempt to make it slightly less thin rather than to replace it.
Why the mechanisms are still worth having
Most existing documentation came from individual discretion, and that is not an argument against the rest of this collection.
They raise the floor: a team relying entirely on discretion has whatever its most conscientious person felt like writing, which is a lottery with a small prize.
They make discretion cheaper: somebody who feels like writing and can finish in six minutes will, where the same person facing an afternoon will not.
And they stop discretion being punished, which is what actually ends it. The usual cause is not an absence of reward but the slow accumulation of a sense that it costs something and counts for nothing.