Why Documentation Feels Like a Myth (and How to Make It Real)

3 min read

Every team agrees documentation is important. Few teams have documentation they trust. Somewhere between "we should document this" and "the wiki says to use a server we shut down in 2021", good intentions get lost.

Documentation isn't actually a myth. But a few persistent myths about it are why so much of it ends up outdated, incomplete or missing. Here they are, and what works better.

1. The myth of the perfectly documented project

Somewhere, there's said to be a project where every function is explained, the README works on the first try and new developers are productive on day one.

Then you open a real repository.

Perfect documentation isn't realistic because code changes faster than anyone can describe it. Aiming for perfect usually means writing nothing, because perfect never fits in this sprint. The better goal is useful: enough to get someone started, explain the important decisions and avoid the most common mistakes.

2. The myth of "I'll document it later"

"Later" is the most optimistic word in software. Later becomes tomorrow, tomorrow becomes next sprint, and by then nobody remembers why the code works the way it does. What's left is the immortal comment: // TODO: explain this.

Spoiler: nobody ever explains it.

The fix is to write documentation while the context is fresh. A short paragraph in the pull request, a few lines in the README, a note on why a choice was made. Five minutes now saves hours of archaeology later.

3. The myth of self-documenting code

"Good code documents itself" is half true. Clear names, small functions and simple structure do make code easier to read. They explain what the code does.

They don't explain why. Why this library instead of the obvious one? Why this odd retry loop? Why does this endpoint return a 200 on error? Those answers live in someone's head until they're written down. And code written under deadline pressure at 2 a.m. rarely documents anything except the time.

Good code reduces the documentation you need. It doesn't remove it.

4. The myth of documentation first

Writing complete documentation before writing code sounds disciplined. In practice, the design changes the moment it meets reality, and the documentation is outdated before the first commit.

A lighter version works well: write a short design note before starting, covering the problem, the proposed approach and the open questions. Then update it when the real decisions are made. It's a sketch, not assembly instructions for furniture you haven't built yet.

5. The myth of the one true format

Markdown or wiki? Inline comments or generated API docs? Teams can debate formats for weeks. The format matters far less than two things: that people can find the docs, and that they are kept next to what they describe.

A simple rule of thumb: keep documentation in the repository, close to the code, and reviewed in the same pull requests. Docs that live elsewhere drift away from reality fastest.

6. The myth of comprehensive documentation

Covering everything from architecture diagrams to every function sounds thorough. In practice, comprehensive documentation is a time capsule: accurate on the day it was written, misleading a few months later. Outdated docs are worse than missing ones, because people trust them.

Document fewer things, and keep them current. The setup guide, the architecture overview and the key decisions matter more than an exhaustive tour of every module.

7. The myth that everyone will contribute

"Everyone will help keep the docs up to date." Then the work quietly falls to the newest team member or the one person who once said they enjoy writing.

Shared responsibility works when it's part of the process. If a change affects behaviour, the pull request updates the docs. Reviewers check it the same way they check tests. That turns documentation from a favor into a habit.

What actually works

  • A README that gets someone running in under an hour, tested by the last person who joined.
  • Short decision records explaining why important choices were made.
  • Docs reviewed with code, in the same pull request.
  • Small, frequent updates instead of big documentation sprints.
  • Deleting outdated pages, because wrong is worse than missing.

Conclusion

Documentation feels like a myth because teams chase a perfect version that can't exist. Aim lower and stay consistent: document the why, keep it next to the code and update it as part of normal work. And when the docs fall short, ask. A good conversation is still documentation, it's just harder to search.