The short version
- People do not read the docs. They message whoever wrote them, because a person is a faster and more reliable interface than a search box.
- This is a rational choice, not laziness: asking takes eleven seconds and works nearly always, while searching takes minutes and often fails.
- The fix is not better organisation or a search upgrade. It is making the doc answer the message.
- Judge documentation by how many questions it removes, not by how much of it exists.
Every company with a documentation problem has the same conversation: we need to document more. Then they document more, and the questions keep arriving at the same people, and the conclusion is that the team has a culture problem.
"They DM the person who wrote it."
What people do instead
Watch what actually happens when someone needs to know something. They think of the person most likely to know, they message that person, and they carry on with something else while they wait. If the person is unavailable, they either guess or park the task.
At no point does searching the documentation feature as a serious first option, even on teams where the documentation is genuinely good. If it appears at all, it is as a second attempt after the message goes unanswered, which is the reverse of what everyone intends.
Why that choice is rational
| Asking a person | Searching the docs | |
|---|---|---|
| Effort to start | About eleven seconds | One to five minutes |
| Success rate | Very high | Uncertain |
| Needs the right vocabulary | No | Yes |
| Handles a partial question | Yes, they infer what you meant | No |
| Confidence in the answer | High, it is current | Low, the page may be stale |
The person wins on every row. The cost, of course, lands on them rather than on the asker, which is precisely why the behaviour persists: the person choosing does not pay.
The third row is the least appreciated. Someone with a question does not know the words the answer is written in. A colleague translates automatically, which is a service no search box provides.
The fixes that do not work
Better organisation. Reorganising the wiki helps whoever did the reorganising and nobody else, because the problem was never structure. It was that the reader has to locate the answer.
Better search. Improves the cases where the reader already uses the right words, which are the cases they would have solved anyway.
Asking people to check first. Fails because it asks the asker to accept a slower, less reliable route out of consideration for someone else. Consideration loses to a deadline every time.
More documentation. Makes it worse. A larger collection has a lower proportion of current pages, and one stale page teaches a reader to distrust all of them.
Make the doc answer the message
The winning move is to stop trying to change the behaviour and change what the behaviour reaches. People will send a message; the question is whether that message has to land on a person.
With StandIn, each person confirms a ninety-second brief at the end of their day, mostly pre-drafted from work that already happened. While they are off, their StandIn answers questions from that brief in their words, with a source under every answer, clearly labelled, and never guessing. The asker does exactly what they were always going to do: phrase the question in their own words and send it. They get the answer immediately, sourced, with no vocabulary problem and nobody interrupted. When the answer is not in the record, it says so and names who to ask.
Documentation still matters for the stable, structural things: a system diagram, a runbook for a rare procedure. What changes is that it no longer has to carry the load it was always failing to carry. See how StandIn works.
A better measure of documentation
Stop counting pages and coverage. Count questions removed.
Pick the five questions your team answers most often, and ask whether a colleague can get each answer without interrupting anyone, in under a minute, and trust it. That is the only measure that correlates with the thing documentation was supposed to achieve. A wiki with thirty current pages that removes those five questions is worth more than four hundred pages that remove none.
Common Questions
Why does nobody read internal documentation?
Because asking a colleague is faster, more reliable, and does not require knowing what the answer is called. It is a rational choice, and the cost falls on the person being asked rather than the person choosing.
Would better search fix it?
Only at the margins. Search requires the reader to use words close to the ones in the document, and someone who does not know the answer generally does not know its vocabulary. That is the gap, and indexing does not close it.
Should we stop writing documentation?
No, but narrow it. Write the stable structural things once and accept they will need periodic refreshing. Do not attempt to document current state or recent decisions in a wiki, because those change faster than anyone will maintain them.
How do we get people to stop messaging the author directly?
Give them something as fast as messaging. Every attempt to change the habit by appeal fails, because the habit is the efficient choice. Change which option is efficient and the habit changes on its own.
When you're off, your StandIn is on.
It answers your teammates' questions from work you've already done, in your words, with a source under every answer.