Limits
What the Writing Is Actually For
The purpose is not a complete record. It is to stop a specific question being asked a fourth time, and most of what follows from that is cheap.
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.
For distributed teams, documentation decisions improve when time and activity are visible in context, which is why it can help to read the product notes alongside the editorial review.
For additional context beyond this collection, see the resources maintained by Canva.
The whole argument of this collection, in the four shapes writing takes
An answer written where the question was asked
8 / 228Eight minutes; the cheapest and most-used thing a team produces
A reason recorded at the moment of deciding
9 / 242Nine minutes; stops the decision being reopened in six months
A procedure written while somebody followed it
30 / 288Thirty minutes, because the author was reading each step anyway
A description written from memory, after the fact
140 / 72Two and a half hours, and this is what most people picture when they hear documentation
four documents · 187 minutes written · 830 minutes saved across 54 readings
Four shapes, 187 minutes written, 806 minutes saved across 54 readings. The first three cost forty-seven minutes between them and account for forty-eight of the fifty-four readings. The fourth costs three times as much as all of them together. One team's own quarter, and the last line of the last panel on this site.
Fifty notes is a long way round to a short conclusion, and the conclusion is worth stating without the apparatus.
Writing things down at work is not about building a record of how a system works. It is about stopping a specific question from being asked a fourth time.
Why that framing changes things
A complete record is unbounded, unachievable and mostly unread. Aimed at it, a team produces overviews, glossaries and twelve-page guides, and gets tired.
Stopping a question is bounded, cheap and verifiable. It takes four lines. You can tell afterwards whether it worked, because either the question stops or it does not.
Everything practical in this collection follows from the second framing and almost nothing follows from the first.
The arithmetic, once more
One person pays, in a specific hour, out of a day that was already accounted for. The benefit arrives later, in minutes, to people who do not know what it saved them.
That is the whole problem. It is not a belief problem, not a tooling problem and not usually a willingness problem.
There are exactly two things that help: making the cost nearly zero, and making the benefit visible to whoever paid.
The three habits
If nothing else survives, these three:
Answer where the question was asked. When somebody asks something you have answered before, put the answer where it persists and send the link. Ninety seconds more than replying in chat.
Write while doing, not afterwards. During the incident, during the procedure, while explaining. A third of the cost and more accurate.
Tell the author it helped. Fifteen seconds. The only feedback that ever crosses the gap, and the thing that keeps the person writing.
The three numbers
A page is usually four lines, not a document.
A document written from memory costs three to five times one written at the time.
And on most teams, one person has written most of what exists, and nobody has ever mentioned it to them.
What this collection has not claimed
That everything can be written down. A small category cannot, and pretending otherwise would have made the rest easy to dismiss.
That every team should write more. Some pages lose — the panel on the home page of this site has one, and so does the page on what not to write.
That there is a system for this. There is not. What there is, in most organisations, is a handful of individuals exercising discretion, and some arrangements that make their discretion cheaper and less thankless.
That any figure here is a benchmark. Every number on every page is one team's record of its own quarter, labelled as such where it appears, and shows a shape rather than setting a level.
The whole collection, in five lines
Everything here reduces to a small number of statements, and they fit on one screen.
- One person pays, in a known hour; many people benefit, later, invisibly.
- That is not a belief problem, a tooling problem or a willingness problem.
- Two things help: make the writing nearly free, and tell the author it was used.
- Most of what needs writing is four lines, written at the moment somebody asks.
- A small residue cannot be written at all, and pretending otherwise discredits the rest.
Nothing in that list requires a tool, a budget, a policy or anybody's permission, which is either encouraging or uncomfortable depending on how long a team has been meaning to start.
The thing to do tomorrow
The next time somebody asks you something you have answered before, put the answer somewhere it will still be in six months, and send them the link.
Then, when you find a page that saves you twenty minutes, work out who wrote it and tell them.
Those two take under two minutes between them and they are the whole argument.
Where to start, if nothing is written at all
A team at zero does not need a plan, a tool or an agreement. It needs the first three things to happen in the right order.
- Keep a tally for a month: one line each time somebody asks something already answered.
- Write the top item as four lines, in the place people already look.
- When somebody uses it, tell the person who wrote it.
That is a month of work measured in minutes, it requires nobody's approval, and it produces the only two things that matter — a page people open, and an author who knows it was opened.
Everything else in these fifty notes is elaboration on those three steps.