Why not
Nobody Is Ever Thanked for a Document
A document's value arrives months later, in private, to people who do not know who wrote it — so the author gets no signal at all, in either direction.
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.
When a documentation effort needs evidence about where working time actually goes, teams can view current features before deciding what should be written or automated.
For additional context beyond this collection, see the resources maintained by Mailchimp.
Four documents from one team, and the weeks somebody opened them, against the week the author last heard anything about them
The deploy runbook
Eleven weeks of use; the author was told once, in week three
A note on why the retry limit is three
Four weeks of use, three of them by people who joined later; the author heard nothing
The onboarding page for the data team
Four weeks of use, one per new joiner; two of the four thanked the author in passing
A design document nobody asked for
Never opened, and the author has assumed for three months that it was useful
four documents · 19 weeks in which somebody opened one of them · the longest wait between writing and a reading was 35 weeks · one never read at all
Four documents, nineteen weeks in which somebody opened one of them, and one never read at all. Usefulness arrives long after the author has stopped thinking about the thing, which is also long after anybody is likely to mention it. The fourth row is the other half of the same problem: silence reads the same whether a document was useful or not. One team's own quarter.
Shipping something produces a response. Somebody notices, something works that did not work before, there is a moment where the thing arriving is visible to other people.
Writing something produces silence. Not criticism, not indifference — silence, which continues for months and then stops being a thing anybody could break.
Why the signal never arrives
Three separate failures, each sufficient on its own.
The timing. The usefulness happens weeks or months after the writing, by which point nobody is thinking about the fact that somebody wrote it.
The privacy. Reading a page is a solitary act. Nothing about it is visible to anybody, including the author, and nothing prompts the reader to mention it.
The attribution. Most documents carry no name, and most readers would not notice if they did. The experience is of finding an answer, not of being helped by a person.
Put together, the person who spent an afternoon writing receives exactly as much feedback as the person who spent an afternoon writing something nobody ever read.
What silence gets interpreted as
Badly, and in a predictable direction.
Nobody concludes from silence that their work was valuable and invisible. They conclude that it was not valuable, which is the simpler explanation and the one most people reach for about their own work.
The fourth row of the panel above is the complementary case: a document that genuinely helped nobody, whose author has spent three months assuming it was fine. The two situations are indistinguishable from inside, which means the feedback channel is not merely weak — it carries no information at all.
The comparison people make
Everybody on a team has a rough sense of which activities get noticed.
| Activity | Noticed by | When |
|---|---|---|
| Shipping a change | Several people | Immediately |
| Fixing something visibly broken | Everybody affected | Within hours |
| Reviewing a colleague's work | That colleague | Same day |
| Answering a question in chat | The asker | Within minutes |
| Writing a page | Nobody | Never |
The last row is the only one with nothing in either of the other two columns, and people are not wrong to notice that.
Answering in chat instead
This table explains a behaviour that otherwise looks irrational: that people will cheerfully answer the same question six times in chat and will not spend ten minutes writing the answer down.
Answering in chat is faster, it is socially warm, and it produces immediate visible gratitude from a named person. Writing the answer down is slower, solitary, and produces nothing.
The person choosing the first option is responding correctly to the incentives in front of them. Any account of this that starts from laziness has misread the situation.
The cheapest repair anybody can make
Tell the author.
Not as a policy, not as a scheme, not as a channel with a name. When a page saves you twenty minutes, find out who wrote it and send them one line saying so.
It costs fifteen seconds, it is the only signal that ever crosses the gap, and it is wildly more effective than any amount of general encouragement — because it is specific, it is evidence, and it arrives from somebody who has no reason to say it except that it happened.
Most people who do this once discover that the author remembers it for a year, which is itself a measure of how rarely it happens.
Why this is not a motivation trick
It is worth being clear that none of this is about making people feel good in order to extract more writing from them.
The feedback is information. An author who never hears anything cannot tell which of their pages were worth writing, so they cannot get better at choosing what to write, so their next page is as likely to be the fourth row as the first.
A team where authors hear back converges, over a year, on writing the things that are actually used. A team where they do not keeps producing a mixture and has no way to improve the mixture.
What an author could do for themselves
The signal is missing and the author is not powerless, though the available moves are modest.
- Keep a list of what you wrote. Two minutes a quarter, and it is the only record that will exist.
- Check the open counts once a quarter, with the caveats on the counting page.
- Notice which questions you have stopped being asked.
- Mention the writing when you describe your own quarter.
None of these produces the warm signal that shipping produces, and together they are enough to tell an author which of their pages worked, which is the information they actually need in order to choose better next time.
What this does not solve
Telling somebody their page helped does not change the fact that the afternoon came out of their week and appeared on no record. That is a separate problem with a separate repair.
It also does not scale into a process. Any attempt to institutionalise it — a weekly thanks channel, a documentation award — converts a real signal into a ritual one, and a ritual signal carries no information, which is where it started.