Most documentation goes unread not because engineers don't read docs, but because most docs are written to look complete rather than to answer the actual question someone has at 2pm on a Tuesday.
2 min read
A README that opens with a company mission statement before explaining how to run the project is optimizing for the wrong thing. The person reading it almost always has one specific, urgent question — "how do I get this running locally," "what does this function actually expect," "why does this exist at all" — and documentation that makes them scroll or search for the answer has already partially failed, regardless of how thorough it is elsewhere.
A few patterns separate the two in practice:
Documentation that's wrong is often worse than no documentation at all — a reader trusts it, acts on it, and only discovers it's outdated after something breaks, at which point they've lost time and trust in every other doc nearby. This is exactly why keeping documentation physically close to the code it describes matters so much: a change that touches the code is far more likely to also touch a comment sitting three lines away than a wiki page nobody thought to open.
The real audience for most internal documentation is a future version of the same team — often the exact person who wrote it, six months later, having forgotten the reasoning behind a decision they made themselves. Writing documentation with that specific, time-pressured reader in mind — someone with an urgent question and limited patience for context they don't yet need — consistently produces more useful docs than writing to sound thorough.
Check your understanding
A quick comprehension check — not tracked, not graded, just for you.
1. According to this lesson, why does documentation often go unread?
2. Why should a working example usually come before a full parameter reference?
3. Why does documentation kept close to the code it describes tend to stay more accurate?
Software Engineering Fundamentals