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) |