There's a belief in many organizations that more documentation is always better. Cover every edge case. Record every decision. Write it all down so nothing gets lost.
It sounds responsible. It isn't.
The Documentation Paradox
Documentation has a cost. It takes time to write. It takes time to read. It takes time to maintain. And here's the paradox: when there's too much of it, people stop reading it altogether.
When everything is documented, nothing stands out. The important decisions get buried in the noise. The critical information gets lost in the pile. People stop trusting the documentation because they can never find what they need.
So they start asking each other instead. "Hey, do you know how this works?" "What was the decision on that?" The documentation exists, but nobody uses it. All that time writing it was wasted.
What to Document
The less you say, the more the things you say actually matter. Here's what's worth documenting:
Document decisions, not discussions. The meeting can be forgotten — the conclusion can't. Nobody needs to know who said what in the debate. They need to know what was decided and why.
Document the "why," not just the "what." The code shows what it does. The documentation should explain why it's that way. Future you (or future teammates) will understand the what. They need help with the why.
Document what a new person would need. Not everything that ever happened — just enough to get someone up to speed. If a new team member can read it in an afternoon and understand the project, you've documented enough.
Good Writing in Disguise
Good documentation is like good writing: it's not about adding more words. It's about removing the unnecessary ones until only what matters remains.
Every sentence should earn its place. If it doesn't help someone understand or make a decision, cut it.