Why not
The Team That Agrees and Still Does Not Write
Most teams that do not document are fully convinced that they should. Treating that as an understanding problem is why so many attempts fail.
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
What the deploy order is
Guessed, then corrected by whoever noticed
Wrong on the ninth occasion
Why the retry limit is three
Re-argued at two planning meetings
The reasoning was in nobody's head
three things nobody wrote down · 20 occasions it cost somebody something
Three things, twenty occasions, and one customer who noticed.
Teams testing a new knowledge workflow can the official resource to establish a baseline, then compare the result after ownership and review rules change.
The broader workflow can also be checked against guidance from YouTube.
What one team wrote in the quarter after agreeing unanimously that it would write more
A note written during a meeting
6 / 100Six minutes, because the person explaining simply typed it as they spoke
Four lines added to an existing runbook
9 / 88Nine minutes, added by whoever had just been asked
A page written because one person was named for it
45 / 126Forty-five minutes on a Thursday by somebody who had agreed to a date
Everything else that was agreed
0 / —Four items, all agreed, none written, all raised again at the next retrospective
four documents · 60 minutes written · 314 minutes saved across 23 readings · one with no saving claimed
Four lines, sixty minutes written, 388 minutes saved across twenty-three readings — and the fourth line is the one worth looking at. Three pages exist because somebody typed while already explaining, or was named with a date. Four do not exist because everybody agreed about them. One team's own quarter, counted at the end of it.
The standard account of a team that does not write things down is that it does not understand the value. The standard remedy follows from the account: explain the value.
On most teams the account is simply wrong, and everything built on it fails for that reason rather than through poor execution.
What the conviction looks like
A team in this position will, in any given quarter, produce several sincere expressions of the belief.
It will appear in a retrospective as an action. It will appear in a planning conversation as a thing that would have helped. It will appear after an incident as the obvious lesson. Somebody will propose a wiki, or a template, or a day set aside for it, and everybody will agree.
None of this is performance. The people saying it have personally been hurt by the absence, recently, and can name the occasion.
What happens to each initiative
The pattern repeats closely enough to describe in general.
A tool is chosen. There is initial enthusiasm and a burst of pages, nearly all written in the first two weeks by two or three people. The pages are structural — a table of contents, a glossary, a page about how to use the wiki — rather than answers to questions anybody has.
Activity falls to near zero by week five. Six months later the content is stale, and its staleness becomes the reason given for why the next attempt should use a different tool.
The thing that was never attempted at any point is allocating the cost.
Why the explanation does not help
Explaining the value of documentation to a team that already believes in it does three things, all mild.
It takes thirty minutes. It produces agreement, which was already present. And it slightly increases the guilt attached to not writing, which makes people less willing to discuss the subject honestly, because the honest answer sounds like an excuse.
That third effect is the damaging one. After enough exhortation, "I did not have time" stops being a report on a real constraint and starts being a thing people are embarrassed to say, so they stop saying it and the real obstacle goes underground.
The question to ask instead
Not "do we agree this matters" — the answer is known — but:
Which hour, belonging to which named person, is this coming out of, and what is that person not doing instead?
A team that cannot answer this does not have a documentation plan. It has a documentation sentiment, and sentiment has already been tried.
The question is uncomfortable because it forces somebody to say that a page is worth more than a change somebody is waiting for, which nobody wants to assert in a planning meeting.
What the panel above shows
Three of the four lines produced pages, and they share a property that is not enthusiasm.
Two of them cost under ten minutes because the writing happened inside an activity that was already happening: somebody was explaining, and typed instead of talking. The cost was never allocated because it was never incurred separately.
The third cost forty-five minutes and happened because one person was named and had agreed to a date.
The fourth line is four items that everybody supported.
The two mechanisms, stated once
Everything in the second half of this collection reduces to one of two things, and it is worth naming them here before the detail.
Make the writing cost almost nothing, usually by attaching it to work that is already happening. This is where most of the available improvement is.
Or allocate the cost explicitly to a person, with a size and a date. This works and does not scale, because each allocation is a small negotiation that somebody has to conduct.
Exhortation is a third thing and it is not a mechanism. It changes the level of agreement, which was already at the ceiling.
The smallest version that has ever worked
A team about to agree for the fifth time can replace the agreement with four lines in a message. Not a plan — a list.
- One person's name.
- One thing to write.
- One length: four lines, a paragraph, a page.
- One date, within the week.
Repeated three times, for three people, that is the whole intervention. It is less impressive than anything that will be proposed in the room, and on the evidence of the panel above it is the only form with a record of producing pages.
The objection will be that this does not scale. It does not. Nothing in this subject scales, which is why the collective versions keep failing.
What to say in the next retrospective
If the action "we should document more" is about to be agreed for the fifth time, the useful contribution is to say that it has been agreed four times and ask what will be different.
Then propose the smallest version that has a name on it: one person, one page, four lines, by Friday. It will feel insultingly modest compared with the ambition in the room.
It is also the version that has, in the panel above, a hundred per cent record, against zero for everything agreed collectively.