I used to think good documentation meant covering every edge case, every configuration flag, every possible error message. I'd spend weeks on a single system design doc, proud of how thorough it was. Then I'd watch the team ignore it completely and come ask me the same questions over and over. That hurt, but it took me a long time to realize the problem was me, not them.
The turning point came when I inherited a legacy infrastructure setup with a hundred-page runbook that nobody had opened in three years. The original author had left, and the doc was full of outdated commands, wrong IP addresses, and steps that assumed a software version we'd patched twice since. The team had learned to work around it by just asking whoever remembered the right way. That's not documentation, that's oral tradition.
I started over. But this time I didn't write for completeness. I wrote for the moment of panic. When a service goes down at 2 AM, nobody wants a history of the architecture decisions. They want the five commands that fix it, in order, with no extra fluff. So I created what I called a "break glass" page — a single sheet that told you exactly how to restart the thing, where the logs lived, and who to call if that didn't work. That page got bookmarked by everyone.
Another thing I changed was the audience. I stopped writing for future me or for some mythical perfect developer. I wrote for the new hire who just joined and has no context. That meant cutting every acronym that wasn't explained, every assumption about prior knowledge, every reference to "as discussed in the planning meeting." I started each doc with a single sentence that told you what problem this thing solved and who should care. If you couldn't write that sentence, you weren't ready to write the doc.
I also learned to embrace imperfection. A short doc that's 80 percent right and updated quarterly is infinitely more useful than a perfect doc that's never updated because it's too painful to maintain. I tell my teams to ship docs the same way we ship code — iteratively. Add a section when someone asks a question for the third time. Update a command when you discover it's wrong. Delete a page when the system it describes no longer exists.
The hardest lesson was about ego. I had to accept that nobody was going to read my beautifully crafted prose. They were going to search for a keyword, scan for a command, and leave. So I stopped writing paragraphs and started writing answers to specific questions. I used plain language, short sentences, and lots of whitespace. I put the most important thing first, always. And I stopped apologizing for not covering every possible scenario.
These days, when I check our docs analytics, I see people actually using them. The runbook gets hits during incidents. The onboarding guide gets followed step by step. And the best feedback I get is silence — nobody asking me questions they could have answered themselves. That's the real win. Documentation isn't a record of what you built. It's a tool that lets you walk away and trust that someone else can keep the lights on.