I have written hundreds of runbooks, architecture docs, and deployment guides. Maybe ten percent of them ever got read by another human. That is a humbling ratio and it took me years to figure out why.

The problem is not that people do not care about documentation. The problem is that most docs answer questions nobody is asking. They are written to prove the author did the work, not to help the reader solve a problem. There is a difference and it shows.

I learned this the hard way when I wrote a forty-page migration guide for a database upgrade. It had diagrams, rollback procedures, even a timeline. Six months later the team did the actual migration and nobody opened my doc once. They Slack'd the same three people who had done it before and copied commands from a old terminal session. I was annoyed until I realized my doc was useless because it explained the system. They needed to know what to type at step seven when replication lag spiked. Those are different things.

The docs that actually get read have a few things in common. They start with the problem, not the feature. Nobody cares about your new event bus architecture. They care that their webhook stopped firing and they need to fix it in the next twenty minutes. Open with that scenario and suddenly you have their attention.

They are also short in a specific way. Not short as in vague. Short as in every paragraph earns its place. If a sentence does not help the reader make a decision or take an action, it does not belong. I cut more words from my docs than I keep now and the feedback improved immediately.

Another thing that works is showing the reader what success looks like early. Before you explain how the thing works, tell them what it does when it is working correctly. A health check endpoint that returns 200. A log line that confirms the message was processed. A dashboard panel that turns green. Give them the destination before the map.

I also stopped writing docs in isolation. Now I sit with someone who is new to the system and watch them try to use what I wrote. Where they pause, where they open a second tab, where they ask a question out loud — those are the spots that need rewriting. You cannot find those spots by re-reading your own work.

The best documentation I have ever seen was a single page with three sections. What this does. How to set it up. What to do when it breaks. That was it. No history section, no glossary, no comparison with the old system. Just the information a person needs at the moment they need it.

I think about that page a lot. It reminds me that documentation is not a writing exercise. It is a service you provide to someone who is stuck. Write for them, not for the archive.