Documentation Quality
STOP - Documentation Freshness
- •Documentation rots faster than code. Stale docs are worse than no docs.
- •If code changed, check which docs need updating - README, CLAUDE.md, API docs, comments
- •Comments explain WHY, not WHAT - If it repeats the code, delete it
Core Principle
"The purpose of comments is to explain things that aren't obvious from the code." — Ousterhout, APOSD
Good documentation:
- •Explains WHY, not WHAT
- •Uses different words than the code
- •Stays synchronized with implementation
- •Describes the non-obvious
Documentation Checklist
1. README Accuracy
- • Does README describe current behavior?
- • Are setup instructions still valid?
- • Do examples still work?
- • Are dependencies current?
- • Is the feature list accurate?
2. Comment Freshness
- • Do comments match the code they describe?
- • Are TODOs still relevant or stale?
- • Do function comments match signatures?
- • Are "temporary" comments actually temporary?
3. API Documentation
- • Public interfaces have doc comments?
- • Parameters documented with types and constraints?
- • Return values documented?
- • Exceptions/errors documented?
- • Examples provided for complex APIs?
4. Changelog Updates
- • Breaking changes documented?
- • New features listed?
- • Bug fixes noted?
- • Migration instructions for breaking changes?
5. Comment Quality (APOSD)
- • Comments describe non-obvious things?
- • Comments use different words than code?
- • Interface comments present (before implementation)?
- • Comments explain "why", not "what"?
- • No comments that repeat the code?
6. Missing Documentation
- • New public APIs documented?
- • New configuration options documented?
- • New environment variables documented?
- • New CLI flags documented?
7. AI Documentation
Check all AI config files that exist in the project:
| File | Tool |
|---|---|
CLAUDE.md | Claude Code |
.cursorrules / .cursorignore | Cursor |
.github/copilot-instructions.md | GitHub Copilot |
AGENTS.md | Copilot Workspace |
.windsurfrules | Windsurf |
.aider.conf.yml | Aider |
.continue/config.json | Continue.dev |
.clinerules | Cline |
.roomodes | Roo Code |
CONVENTIONS.md | Various |
- • AI docs reflect current architecture?
- • Agent/skill descriptions accurate?
- • File structure documentation up to date?
- • All AI config files consistent with each other?
- • Version numbers synchronized?
Comment Anti-Patterns
| Anti-Pattern | Example | Problem |
|---|---|---|
| Repeat the code | i++ // increment i | Zero value |
| State the obvious | // loop through users | Noise |
| Stale comment | Comment says X, code does Y | Dangerous |
| TODO forever | // TODO: fix this from 2019 | Clutter |
| Commented-out code | Dead code masquerading as comment | Confusion |
Comment Patterns That Add Value
| Pattern | Example | Value |
|---|---|---|
| Explain rationale | // Use insertion sort: n < 10 always | Design decision |
| Warn about non-obvious | // Must call before X, else crash | Prevent bugs |
| Summarize algorithm | // Binary search on sorted timestamps | Quick understanding |
| Document edge case | // Empty list returns -1, not null | Clarify behavior |
| Reference external | // Per RFC 7231 section 6.5.4 | Authority |
Severity Guide
| Finding | Severity |
|---|---|
| README contradicts actual behavior | CRITICAL |
| API doc says wrong return type | CRITICAL |
| Stale comment causes bug risk | CRITICAL |
| CLAUDE.md describes deleted/renamed files | CRITICAL |
| New public API undocumented | IMPORTANT |
| Breaking change not in changelog | IMPORTANT |
| CLAUDE.md missing new features/agents | IMPORTANT |
| AI doc version mismatch | IMPORTANT |
| Stale TODO from distant past | SUGGESTION |
| Could add clarifying comment | SUGGESTION |
| Minor README improvement | SUGGESTION |
Questions to Ask
- •"If someone reads only the docs, will they use this correctly?"
- •"If the code changes, which docs need updating?"
- •"Does this comment tell me something the code doesn't?"
- •"Is this TODO actionable or just noise?"
Chain
| After | Next |
|---|---|
| Docs need code changes | Back to implementation |
| Docs verified | Done (pre-commit gate) |