Why does documentation always go out of date?
Because documentation and the code it describes are coupled in meaning but decoupled in enforcement — nothing breaks when they diverge, so they diverge.
The core mechanism. Code has a merciless feedback loop: it is compiled, tested, run, and it fails loudly when wrong. Documentation has no such loop. A wrong sentence in a README produces no error, no failing test, no alert. It fails silently, and it fails on someone else, later.
The compounding factors:
Documentation lives elsewhere. In a wiki, a separate repository, a Confluence page — somewhere the developer changing the code is not looking. Out of sight, and not in the diff a reviewer reads.
Nobody owns it. It belongs to everyone, which reliably means no one.
Updating it is unrewarded. Shipping the feature is visible; correcting the page describing it is not.
The person writing it knows too much. They cannot see which assumptions they have left implicit — the curse of knowledge, which is also why documentation is frequently unhelpful even while accurate.
Wrong documentation is worse than none, because it is trusted. Absent documentation makes someone read the code; incorrect documentation sends them confidently in the wrong direction.
What actually works, in rough order of effectiveness:
Make it executable. Tests are documentation that fails when it becomes wrong. Doctests, runnable examples in the README verified by CI, and generated API clients all bind the description to reality.
Generate what can be generated — API references from schemas or annotations, so the source of truth is singular.
Keep it in the repository, next to the code, so it appears in pull requests and can be reviewed with the change.
Document the durable things. Why a decision was made, what alternatives were rejected, what constraints applied. Architecture decision records age well precisely because they describe a moment rather than a current state.
Avoid documenting the volatile. Step-by-step UI walkthroughs and exact file layouts rot fastest.