TL;DR — Engineering docs go stale because they live in a different place from the code, get updated on a different schedule, and nobody owns them. Docs-as-code, sync-with-PRs, and a quarterly archive review keeps docs current and useful.
Stale docs are worse than no docs. New engineers trust them, get burned, learn not to trust them, and the documentation system loses its only consumer. Keeping docs current is a process problem, not a content problem.
Why docs go stale
- They live in a wiki separate from the code
- Updating them is “optional”
- No single owner — everyone's responsibility is no one's
- No mechanism that fails CI when docs and code diverge
The pattern that works
1. Docs in the code repo
Markdown files alongside the code they describe. Architecture docs at the repo root. Module-level docs in each module's folder. API docs generated from code where possible.
2. PR template that mentions docs
Every PR template asks “did docs change?”. Not a checkbox for compliance — a reminder. PRs that touch behaviour without touching docs get flagged in review.
3. Linked docs in PR descriptions
The PR description references the doc(s) it updates. Future engineers reading the PR find the doc. Future engineers reading the doc find the PRs that shaped it.
4. Quarterly archive review
Once a quarter, walk the docs tree. Mark stale documents. Either update or archive. Archived docs go to an archive/ folder, not deleted — they are useful as history.
What we document
- Architecture decisions — ADRs, one per decision, never edited (only superseded)
- Module overviews — what it is, what it does, what calls it, what it calls
- Setup guides — how to get a working dev environment
- Runbooks — on-call procedures, deploy steps, recovery procedures
- API references — auto-generated from code where the language supports it
What we deliberately do not document
- How code works — the code is the truth
- Project goals — they drift; write them in the planning doc instead
- Tutorial-style content — gets stale fastest, lowest value
The single rule
Docs that nobody reads should be deleted, not refreshed. The repo is not a museum.
Frequently asked questions
Should every codebase have a wiki?
No. Wikis are where docs go to die. Docs that live next to the code they describe, in the same repo, in the same PR cycle, stay current.
Who owns docs?
Whoever owns the code. There is no separate docs team. The PR that changes code also updates the docs; CI enforces it.
Working on something similar?
T-Square architects, builds and operates production systems for learning, AI and custom software products. Talk to a senior engineer for a second opinion.