Have you ever opened a project README, read it from start to finish, and still had no idea how to run the thing? The problem is rarely a lack of documentation. It is documentation nobody trusts.
The problem isn't a lack of docs; it's docs nobody trusts
Every team has a full docs/ folder. Nobody reads it. Because the first time someone followed a step-by-step guide and it was wrong, the docs became fiction. From then on, everyone goes straight to the code or asks in chat.
Good docs aren't long docs. They're docs you read and trust. Everything else in this article is about earning that trust.
The README answers the first 5 questions
When someone opens your repo, they usually have five questions, almost always in this order:
- What is this?
- How do I run it locally?
- How do I run the tests?
- How do I contribute?
- Where do I ask for help when I get stuck?
If the README answers these five questions within thirty seconds of reading, it has done its job. Everything else is a bonus. And be careful: everything you put before those answers — a pretty badge, the project's history, an architecture diagram — becomes an obstacle between the person and what they need. Push that content further down.
Explain why, not just how
The how is already visible in the code. retry(3) is obvious to anyone reading the line. What nobody can guess is why three instead of five. Or why a retry exists at all.
Docs that only describe what the code does are redundant and age quickly: the code changes, and the docs start lying. Docs that explain the decision survive refactoring. So record the reason, the trade-off, and the approach you tried and abandoned. git blame won't give you that at two in the morning.
Docs far from the code are dead docs
Documentation that lives in a forgotten Confluence space dies the day after deployment. Nobody updates what they don't see in their normal workflow.
Bring the explanation closer to what it describes:
- A README at the root of each module, not just at the repo root
- A comment above the strange function, explaining what makes it strange
- A short ADR — one decision, half a page — in the project folder itself
The shorter the distance between the code and its explanation, the more likely the explanation is to remain true when the code changes — because it is there, in the same diff, asking to be updated.
An example is worth more than three paragraphs
Nobody reads the textual description of a parameter. Everyone looks for the example, copies it, and adapts it. A code block that runs teaches faster than any carefully written prose.
Even better: an example that is tested. If the README snippet runs in CI — even if it's just a simple test that executes the example — it can never lie for long. Docs that break the build when they become outdated practically maintain themselves. It's the cheapest trick for preventing rot.
Docs that lie are worse than missing docs
Missing docs are honest: you know you'll have to ask someone or read the code. Docs that lie cost an hour following a path that no longer exists — and they also destroy your trust in everything else that is written.
So treat docs like code:
- Deleted a feature? Delete its docs in the same PR.
- Changed a step? Change the text now, not "later."
- Won't maintain it? Delete it.
A README with three true lines is worth more than thirty lines of lies. Write less, but write what is true today. Documentation doesn't die because it's short — it dies because it's false.
