For years I thought good technical documentation meant comprehensive documentation. If a system had forty endpoints, I wrote forty endpoint descriptions. If a deployment had twelve steps, I wrote all twelve, plus a troubleshooting section with every possible error code. The result was a wiki that looked impressive and got read by almost nobody. When a new developer joined the team, I'd send them the docs. They'd skim for ten minutes, then come ask me questions anyway.
The wake-up call came when we shipped a new internal payments API. I spent two weeks writing a reference guide. It covered authentication, rate limits, idempotency keys, webhook signatures, everything. A month later, our support channel was full of the same three questions. One engineer admitted he hadn't finished the guide because it was 'like reading a phone book.' That stung, but he was right. I had documented the system, not the work people actually needed to do.
So I rewrote it. Instead of forty endpoint sections, I wrote three walkthroughs: charging a card, refunding a charge, and handling a failed webhook. Each walkthrough started with a real scenario, showed the exact request and response, and included the specific error you'd hit if you forgot an idempotency key. I deleted the giant reference section and replaced it with a one-page cheat sheet of common status codes. The new guide was maybe a fifth the length. Support tickets dropped by more than half within two weeks.
That experience changed how I think about docs. People don't read documentation to learn a system. They read it because they're stuck or about to make a mistake. So now I write for the moment of confusion. I picture a developer at 4:30 on a Friday, tired, trying to get something working before the weekend. What is the fastest path from 'I'm stuck' to 'it works'? Usually that's not an exhaustive spec. It's a short example they can copy, a note about the one thing that trips everyone up, and a clear sentence about what happens if they skip a step.
I also started asking the support team what questions they answer repeatedly. That's the best documentation roadmap I've found. If three people opened a ticket about the same confusing setting, the docs failed, not the users. I'd rather fix the doc than answer the ticket again.
The hardest part for me was letting go of completeness. I still feel a pull to document every parameter, every edge case. But I've learned that a doc people actually read is a doc that respects their time. It answers the question they have right now and gets out of the way.