Keep Docs Alive: Three Reminders, One Direction
Put each doc change in the same pull request as the code. Add three reminders: on code change, on every push, and every month. Let changes flow one way.
Code has code review. Who approves a doc?
My answer: put the doc change in the same pull request as the code. The same reviewer approves both.
Three reminders
The monthly clean-up comes from the Bullet Journal “migration”. Each month, you copy open items to a new page by hand. If an item is not worth copying, you drop it.
AI helps most with the first reminder. When a pull request changes code, AI can draft the doc diff, and a person reviews it. This fixes the “stops matching the code” cause from Name the Pain Before the Tool.
The second reminder runs the strict rules from Strict Rules Only Where a Machine Checks.
Changes flow one way
When two copies disagree, the copy further from the code is wrong.
- Doc vs code: the doc is wrong.
- Wiki vs repo: the wiki is wrong.
PRDs follow the same rule. PM talks with engineering, and then my team writes the PRD. We own it, so it follows the same flow. If PMs write PRDs themselves later, we change the flow then.
Where to start
| Reminder | A place to start |
|---|---|
| When code changes | a CI step that looks at the changed files. If app/x changed but docs/x did not, it warns in the pull request |
| On every push | a Markdown linter, a link checker, and a field check, inside the CI lint step that you already have |
| Every month | a scheduled CI job (GitHub Actions, GitLab CI, Jenkins) that opens a ticket (Jira, Linear) for docs with an old “last checked” date |
| Copy to the wiki | a CI step that publishes Markdown to the team wiki, for example mark for Confluence |
That is only a starting point. Pick and research the tools yourself.
When docs go through the same door as the code, they do not get left outside.
References
- Bullet Journal: the monthly migration
- GitLab handbook: how GitLab uses its handbook
- Software Engineering at Google, chapter 10: Documentation (g3doc)
- mark: publish Markdown to Confluence
Related: read the series summary: what to take back to your team, revisit Name the Pain Before the Tool, see why docs go stale in the first place, or go back to the series overview: Docs in the AI Era.