Documentation is the lowest-status quality signal on most engineering teams. Tests have their own role on the team. Type coverage has dashboards. Even code style has its linters. Docs have whoever gets around to it.
This is a mistake. The state of a codebase's documentation is a leading indicator of the state of the team's understanding of its own code. And understanding is the thing that collapses first when a team is under pressure.
What documentation actually reveals
A good README means the team agrees on what the project is, how to run it, and what problem it solves. If the README is out of date, something broke in the team's shared understanding of those three things.
Accurate environment variable docs mean someone is paying attention to configuration. If the README lists 12 env vars and the code uses 24, half of your runtime configuration is undocumented. New engineers will ship with defaults they do not understand.
Current API documentation means the people who wrote the API still agree on what it does. Drift between the code's behaviour and the docs is a reliable sign that the API is evolving without being communicated.
Module-level comments mean somebody thought about the module's purpose beyond what was needed to make the current change work. Absence is a signal of change-by-change accretion.
None of these are about writing prose. They are about whether the team has bothered to articulate, for its future self, what the code is supposed to do.
The specific things to document
Not a creative writing exercise. There is a short, universal list.
- The README: what the project is, how to run it locally, how to run tests, where the deployment pipeline lives. Four sections minimum.
- Environment variables: every var referenced in code should appear in the README or a
.env.example. Missing ones are a bug. - Public interfaces: HTTP endpoints, exported functions, database schemas. Every public surface should have a docstring or type signature that matches the implementation.
- Operational runbooks: how to roll back, how to rotate a secret, what to do when the main service goes down. Written before you need them.
- Architectural decisions: not every decision, but the major ones. Why you chose this database, why you kept the old auth system, why you broke up the monolith.
That list covers 90% of the value. Everything else is optional.
The specific things NOT to document
Implementation details of private functions. The code is the documentation for those. If the code is hard to read, fix the code.
Things that change weekly. If a document has to be updated every sprint, it is the wrong abstraction. Either make the thing declarative (config, types, schema) or accept it is not documented and put it in chat history instead.
Auto-generated API docs without prose. Swagger output is a schema, not documentation. Useful, but not a replacement for "here is what this API is for".
Why documentation drifts
Docs decay because the incentives are weak. Writing them is not celebrated. Updating them is not required. The code review system has no hook for "your PR changed the behaviour without updating the docs".
Two things close the gap.
Automated drift detection. Compare documented env vars against those referenced in code. Compare documented API endpoints against routes defined in code. Fail CI when they disagree. The documentation cannot lag indefinitely because CI will catch it.
Documentation as part of the PR. Any PR that changes public behaviour includes the doc update. Reviewers refuse PRs that do not. This is cultural, not mechanical, and it only works if senior engineers enforce it consistently.
What documentation tells you about the team
A codebase with clean, accurate, current documentation is almost always written by a team that can still explain what it built. A codebase with stale, incomplete docs is almost always one where new engineers take weeks to onboard, where bugs hide in behaviour nobody has described, and where refactoring is scary because nobody knows what will break.
Doc quality correlates with many other quality signals: test clarity, API consistency, architectural coherence. Not because docs cause those. Because teams that care enough to write docs also care enough to do the other things.
That is why documentation is a quality signal. Not the content. The act.
