Cheaper
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 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.
Teams testing a new knowledge workflow can remote work activity reports to establish a baseline, then compare the result after ownership and review rules change.
For a separate specialist reference on publishing and digital practice, consult Substack.
What one team produced in the quarter after adopting a documentation tool, and the weeks each was opened
A page about how to use the new wiki
Written first, opened twice, both in the first fortnight
A table of contents for the wiki
Never opened
A glossary
Never opened
Four pages answering actual questions
Written in weeks five to nine, opened in ten separate weeks
four documents · 12 weeks in which somebody opened one of them · the longest wait between writing and a reading was 30 weeks · two never read at all
Four rows, twelve weeks in which somebody opened one of them, and two never read at all. The first three were structural: documents about the documentation. They were written first because they are the easy part, and between them they were opened twice. One team's own quarter after a tool adoption.
A team that decides to take documentation seriously almost always begins the same way: choosing a tool, then building a structure inside it.
A home page, a table of contents, a naming convention, a page explaining how to use the wiki, a glossary. Two weeks of visible activity, and at the end of it no question has been answered.
Why the container gets built first
It is the only part that can be done without knowing anything.
Writing about the deploy order requires knowing the deploy order and having the time of the person who does. Writing a table of contents requires neither, and it feels like progress, and it is something everybody can agree on.
It is also the part that looks most like what documentation is supposed to look like, which matters when people are watching a new initiative.
What it costs
Not much time directly. The damage is in what it consumes.
Enthusiasm has a short half-life. The burst of goodwill that follows a decision to document lasts about three weeks, and if it is spent on structure there is nothing left for content.
It also sets the shape. Having built a hierarchy, people feel obliged to write into it, which produces subject-shaped documents rather than question-shaped ones — the failure described two pages earlier.
The inverse order
Write nine answers. Then, if the pile is awkward to navigate, build the smallest structure that fixes the awkwardness.
Structure built after content is minimal, because it only has to organise what exists. Structure built before content is maximal, because it has to anticipate everything.
The nine answers also tell you what structure you need, which is usually much less than anybody would have designed.
The tool question
Teams spend weeks on this and it matters less than almost anything else in this collection.
The only properties that count: people can find things in it, people can edit without ceremony, and it is somewhere people already go.
The last is the one most often ignored and the most important. A superb tool that requires opening a second application loses to a mediocre one that sits beside the work, because the retrieval step is the thing that stops a five-minute task.
Where the pages should live
Next to the thing they are about, as a default, rather than in a central store.
A note about a service beside that service's code. A note about a client with that client's material. A note about the deploy in the deploy directory.
The objection is that this is scattered and nothing is findable. In practice it is more findable, because people look where they are working, and a central store requires remembering that the central store exists.
A central index linking outward is cheap and solves the remaining case.
The page about the wiki
The first row of the panel is a page explaining how to use the documentation tool, opened twice in a quarter.
It is worth noticing what it represents: effort spent on the documentation of the documentation, which is a reliable sign that the project has turned inward. Teams that produce several of these have usually stopped answering questions some weeks earlier.
The three properties that matter in a tool
Teams spend weeks choosing and the criteria that predict use are short.
- People already go there. A superb tool one click away loses to a mediocre one with no click.
- Editing takes no ceremony. If correcting a typo needs a pull request, nobody corrects anything.
- Things can be found. Search that works, or a location obvious enough not to need it.
Everything else — formatting, hierarchy, permissions, templates, integrations — is below the line that determines whether anybody writes. A team arguing about the second tier has usually not established that the first tier is the problem.
Starting without a decision
The strongest version of this argument is that none of it requires a decision at all.
A team that wants to write more does not need a tool, a structure, an initiative or an agreement. It needs one person to answer tomorrow's question in a file instead of in chat, and to send the link.
Everything else is optional, and most of it is better postponed until there is something to organise.
What to do with the fortnight of attention
A decision to take documentation seriously buys about three weeks of goodwill, and where it is spent determines whether anything survives.
Spent on structure, it produces a home page, a contents list and a naming convention, and runs out before any question has been answered.
Spent on answers, it produces eight or nine short pages that people open for months afterwards, and the structure can be assembled later from what exists.
The second is less satisfying to report on at the end of the fortnight, because a pile of short notes looks like less work than a hierarchy. It is also the only version with anything left in it six months later.