tomevault-io Documentation Maintenance
Announce at start: "Following the doc-maintenance skill to keep docs in sync."
Core Rule
Every code change has a documentation blast radius. Map it before committing.
Process
1. Map — Identify Affected Docs
After any code change, check:
- README mentions this feature?
- API docs cover this endpoint/function?
- Inline comments reference this behavior?
- Configuration docs list this setting?
- Architecture docs describe this component?
- CHANGELOG needs an entry?
2. Update — Same PR, Same Commit
| Change Type | Docs to Update |
|---|---|
| New API endpoint | API docs, README (if public), CHANGELOG |
| Changed behavior | Inline comments, user-facing docs, CHANGELOG |
| New configuration | README, environment docs, config reference |
| Removed feature | All references, migration guide, CHANGELOG |
| Renamed entity | All references (grep for old name) |
3. Scaffold — New Features Need New Docs
If a feature doesn't have documentation yet:
- Create a minimal doc (title + one-paragraph overview + basic usage)
- Add to navigation (README, AGENTS.md, or equivalent index)
- Mark TODOs for sections to expand later
4. Verify — Docs Match Code
- Code examples in docs actually work
- Links to source files are correct
- Version numbers are current
- Screenshots/diagrams reflect current UI
Red Flags — STOP
| Signal | Action |
|---|---|
| PR has code changes but no doc updates | Check the blast radius map |
| "I'll update docs later" | Update now — later never comes |
| Docs describe behavior that no longer exists | Delete or update immediately |
| New feature merged without any documentation | Create minimum viable doc before next task |
Related Skills
| When | Invoke |
|---|---|
| Writing the code that needs docs | planning |
| Ready to submit docs with code | pr-writing |
| Reviewing existing doc quality | code-review |
Deep Reference
For principles, rationale, anti-patterns, and examples:
guides/doc-maintenance/doc-maintenance.mdguides/documentation-guidelines/documentation-guidelines.md
Converted and distributed by TomeVault — claim your Tome and manage your conversions.