SA-201c · Module 1
Keeping Documentation Current
3 min read
Stale documentation is worse than no documentation. No documentation says "you need to investigate." Stale documentation says "here is the answer" — and the answer is wrong. The team that trusts stale documentation makes decisions based on a system that no longer exists. The cost of stale documentation is measured in debugging time, wrong decisions, and eroded trust in the documentation practice itself.
- Documentation Reviews in PRs Include documentation as a code review criterion. "Does this change affect any documented interface, data flow, or architecture decision?" If yes, the documentation update is part of the PR, not a follow-up task. Documentation that is updated with the code stays current. Documentation that is updated separately falls behind.
- Freshness Indicators Add a "last verified" date to every documentation page. Not "last updated" — "last verified." A page verified six months ago by an engineer who confirmed it matches the current system is valuable. A page updated two years ago with no verification is suspect. Freshness indicators tell the reader how much to trust the content.
- Quarterly Documentation Audit Once per quarter, review the documentation pyramid. Is the overview still accurate? Do the component diagrams reflect the current architecture? Are the ADRs complete through the most recent significant decision? A 90-minute quarterly review catches drift before it becomes dangerous.
Do This
- Make documentation updates part of the PR process — update the docs with the code
- Add "last verified" dates to every page — freshness indicators build reader trust
- Conduct quarterly documentation audits — 90 minutes prevents 9 months of drift
Avoid This
- Treat documentation as a separate task to be done "when there is time" — there is never time
- Trust documentation without checking its freshness — stale docs are wrong docs
- Skip the audit because "the documentation is mostly up to date" — mostly is where the bugs live