We had a new engineer join the team, and within a week, they asked a question that was answered in the documentation.
Not buried in the documentation. On the first page. In bold.
My first instinct was frustration. We'd spent weeks writing those docs. They were comprehensive, well-organised, even had diagrams. And here was someone who'd apparently skipped straight to asking a human.
Then I remembered that I do the same thing. Everyone does.
Documentation is a strange artifact. We write it because we believe it will save time. We maintain it because we feel guilty when it's out of date. We point people to it when they ask questions we've already answered.
But almost nobody reads it voluntarily.
This isn't because people are lazy. It's because documentation solves the wrong problem.
When someone is stuck, they don't want to read. They want to be unstuck. Reading requires context-switching, searching, evaluating whether the thing you found is still accurate. Asking a person is faster, even if the person just points you to the documentation.
The act of asking is itself valuable. It confirms you're looking in the right place. It surfaces nuance that the docs might have missed. It builds a relationship.
I've started to think of documentation differently. Not as a replacement for conversation, but as a reference for after the conversation. Something you consult once you already know what you're looking for.
The best documentation I've seen isn't comprehensive. It's searchable. It answers specific questions in specific contexts. It assumes you already know what you need and just need to remember the details.
The worst documentation tries to teach. It starts from first principles, builds up context, explains the why before the what. This is useful for exactly one person: the author, who is trying to organise their own thoughts.
For everyone else, it's a wall of text between them and the answer.
We eventually stopped writing long-form documentation. Instead, we wrote short answers to specific questions, organised by the question itself. "How do I deploy to staging?" "What happens if the queue backs up?" "Where are the API keys stored?"
People still asked questions. But now, when we pointed them to the docs, they actually found what they needed.
The documentation didn't replace conversation. It made conversation shorter.