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:

CLAUDE.md

.cursorrules

.cursorignore

.github/copilot-instructions.md

AGENTS.md

.windsurfrules

.aider.conf.yml

.continue/config.json

.clinerules

.roomodes

CONVENTIONS.md

• 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

i++ // increment i

// loop through users

// TODO: fix this

Comment Patterns That Add Value

// Use insertion sort: n < 10 always

// Must call before X, else crash

// Binary search on sorted timestamps

// Empty list returns -1, not null

// Per RFC 7231 section 6.5.4

Severity Guide

Questions to Ask

1. "If someone reads only the docs, will they use this correctly?"
2. "If the code changes, which docs need updating?"
3. "Does this comment tell me something the code doesn't?"
4. "Is this TODO actionable or just noise?"

Chain