Limits
What a Tool Cannot Fix
Changing where documentation lives addresses a problem most teams do not have, and the burst of activity afterwards is mistaken for a change in culture.
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.
Where the real question is capacity rather than willingness, the detailed overview can supply the work-pattern evidence that a documentation discussion otherwise lacks.
For a separate specialist reference on publishing and digital practice, consult Content Marketing Institute.
One team's output across a run of tool migrations, with the weeks somebody opened the new material
After the first migration, to a wiki
Eleven pages in the first fortnight, nine of them structural; three weeks of openings
After the second, to a documentation site
Eight pages in three weeks, then nothing; four weeks of openings
After the third, back to files in the repository
Four pages, written slowly, opened in seven separate weeks +2 beyond week 40.
Pages that survived all three migrations
Two pages, both answering questions people actually had
four documents · 18 weeks in which somebody opened one of them · the longest wait between writing and a reading was 39 weeks
Four rows, eighteen weeks in which somebody opened one of them. Each migration produced a burst and then silence. The only rows with sustained use are the third, where the tool sat beside the work, and the fourth, which is two pages that survived everything because people needed them. One team's own year.
A team that is not writing will, at some point, change its documentation tool. The new one is better. There is a burst of activity. Within six weeks the output returns to what it was.
This happens often enough to be worth understanding rather than repeating.
What a tool can genuinely fix
Three things, and they are real.
Findability, if the old place was genuinely unsearchable.
Friction of access, if the old place required opening something people did not otherwise open.
Editing, if the old place made correction awkward enough that nobody corrected anything.
Where one of those is the binding constraint, a migration helps and the improvement persists.
What it cannot fix
The cost of writing, which is the time of a person who does not have it.
The invisibility of the benefit, which is a property of how reading works rather than of where the page is.
The absence of anybody named to do it.
Those are the three constraints this collection has been about, and no tool touches any of them.
Why the burst is misread
The fortnight after a migration produces pages, which looks like the tool working.
What is actually happening is that a change has created a moment of collective attention, and people do things during moments of collective attention. The same burst follows a retrospective, an incident, or a new manager arriving.
The pages produced in that fortnight are also, characteristically, structural — a home page, a contents list, a how-to-use guide — for the reasons set out earlier. They are the pages that can be written without knowing what anybody needs.
The migration tax
Each move costs more than anybody plans.
Existing content has to be moved, which is boring work that falls on whoever cared most. Links break. Half the content does not survive, usually the half nobody championed. And the team spends several weeks unsure where things are, during which nobody writes anything because they do not know where to put it.
Three migrations in a year, which is what the panel shows, is a team that has spent most of its documentation capacity on relocation.
The property that actually matters
Of all the things a tool can have, one predicts use: whether it sits in a place people are already in.
The third row of the panel is files in the repository — a worse tool by most measures, with poorer search and no formatting — and it is the only row with sustained writing afterwards. The reason is that nobody had to go anywhere.
A superb tool one click away loses to a mediocre tool with no click, because the click is enough to stop a five-minute task.
What the surviving pages have in common
The fourth row is two pages that outlived three migrations.
They were moved each time, by somebody, because people were using them and would have complained. That is the only property they share: they answered a question people actually had.
Nothing about tooling produced them and nothing about tooling would have prevented them.
What a migration can and cannot change
Worth separating before the fortnight of enthusiasm is spent, because the two lists do not overlap at all.
| A tool can fix | A tool cannot fix |
|---|---|
| Findability, if search was genuinely broken | The cost of an hour nobody has |
| Friction, if people had to open something else | The invisibility of the benefit |
| Editing, if correction was awkward | The absence of anybody named to do it |
The right-hand column is the subject of this entire collection. A team that cannot point at a specific item in the left-hand column is about to pay the migration tax for another fortnight of structural pages.
Before changing anything
Two questions worth answering honestly.
Is the current tool the reason nothing is being written? If people cannot name a specific obstacle, the answer is no.
What would we do differently in the new one? If the answer is "organise it properly", that is a plan to spend the attention on structure again, and the previous two migrations suggest how that ends.
A team that cannot answer both is about to pay the migration tax for another fortnight of structural pages.
What each move actually costs
Each move costs more than anybody plans for, and the costs are predictable enough to list in advance.
- Existing content has to be moved, which is dull work falling on whoever cared most.
- Links break, including links from outside the documentation.
- Roughly half the content does not survive, usually the half nobody championed.
- For several weeks nobody is certain where things go, so nobody writes anything.
Three migrations in a year — which is what the panel above shows — is a team that has spent most of its documentation capacity on relocation, and has the structural pages to show for it.