Counting
Nobody Knows It Helped, Including the Reader
A page's benefit is experienced privately, by somebody who does not know who wrote it, weeks after the writing — so the author learns nothing at all.
What nobody wrote down here, and what it cost
That the runbook saved somebody a morning
Nobody told the author
Six occasions, none reported back
That a note ended an argument
The author never heard
Both times from people who joined later
two things nobody wrote down · 8 occasions it cost somebody something
Two things, eight occasions, and the author heard about none of them.
Documentation is easier to defend when the team can connect it to measurable time saved; project-based time reports provides an operational reference for that conversation.
The broader workflow can also be checked against guidance from web.dev.
Four pages and the weeks somebody opened them, against what the author ever heard
The deploy runbook
Eight weeks of use; the author heard once, in passing, in week nine
A note on why the retry limit is three
Four weeks of use, all by people who joined after it was written; nothing reported
A four-line answer added to an existing page
Seven weeks of use; the author does not know the page was ever opened
A page the author believes was useful
Never opened, and the belief is three months old
four documents · 19 weeks in which somebody opened one of them · the longest wait between writing and a reading was 37 weeks · one never read at all
Four pages, nineteen weeks in which somebody opened one of them, and one never read at all. The author of the third has no idea it is the most-used thing they wrote. The author of the fourth believes the opposite of the truth. Silence carries no information in either direction. One team's own three quarters.
Somebody opens a page, finds what they need, and gets on with their day. Nothing about that event is visible to anybody else, and nothing about it reaches the person who wrote it.
That is the ordinary case, repeated hundreds of times, and it means the person doing the writing has no information about whether any of it worked.
Why the reader does not notice
The experience of using documentation is not an experience of being helped. It is an experience of finding something, which feels like searching successfully rather than like receiving a gift.
There is no moment of attribution. The reader does not think about who wrote it, usually does not look, and would have to make a deliberate effort to find out.
They also do not experience a saving. They never had the counterfactual morning of working it out, so there is nothing to be grateful for — only a question that turned out to be easy.
What the author experiences
Nothing, indefinitely.
And since silence is the same whether the page was useful or useless, the author's belief about their own work is shaped by nothing but their own guess. The panel above has an author who does not know their best page is being used weekly, and one who believes a page helped when nobody has opened it.
Both of those are failures of the same missing channel.
Why this is more than a morale problem
An author who gets no feedback cannot improve what they choose to write.
The useful skill in documentation is not writing — most people write adequately. It is choosing: which four lines, about which thing, at which moment. That skill is learnable only from knowing which of your pages people used.
Without the signal, a person writes the same mixture of useful and useless pages for years, and the proportion never shifts.
What the signals could be
Three, in ascending order of how much work they take.
Somebody says so. Free, carries the most, happens almost never, and is the subject of the next page.
Numbers. Most tools can report that a page was opened and how often. Nearly nobody looks, and the looking takes two minutes.
Questions that stop. A question that was asked seven times a quarter and is now asked once is evidence, and it is available to the person who was being asked, which is usually the author.
The third one is the best and nobody uses it
Worth dwelling on, because it requires no tool and no social act.
If you wrote something because you were tired of being asked, you will know within a month whether it worked, by whether you are still being asked. That is a clean measurement, it costs nothing, and it is available precisely to the people whose motivation matters most.
The tally from the earlier section is the instrument. Keep it for a month before writing and a month after.
What to do with a page nobody opened
Not nothing, and not guilt.
Find out whether it is unfound or unwanted. Those have different repairs: an unfound page needs a better title, a link from where people look, or a move; an unwanted page answers a question nobody has, and the honest response is to leave it and write something else.
The distinction is usually settled by asking two colleagues whether they knew it existed.
The three available signals
None of them is good and all three are better than the silence that is the current state.
| Signal | Cost | How often it happens |
|---|---|---|
| Somebody says so | Free | Almost never |
| Open counts | Two minutes a quarter | Almost never |
| Questions that stop | Free, if a tally exists | Available and unused |
The third is the best of the three and requires no tool and no social act: if you wrote something because you were tired of being asked, you will know within a month whether it worked by whether you are still being asked.
The asymmetry that remains
Even a team doing all of this well has an imbalance that cannot be removed.
Shipping produces immediate, public, attributed feedback. Writing produces, at best, a number seen by one person some weeks later.
Nothing makes those equal. What the rest of this section is about is making the second one exist at all, which is a lower bar and is currently not cleared.