Documentation Review

The Problem

Documentation rots faster than code. A README written 6 months ago references installation steps for a package manager the team abandoned. API docs show parameters that were renamed. Code examples use deprecated methods that throw warnings. Onboarding guides skip “obvious” steps that only make sense if you have been on the team for a year. Outdated docs are worse than no docs — they waste hours as developers follow instructions that lead to errors and then doubt whether the rest of the documentation is trustworthy.

The Prompt

Review the following documentation for accuracy and completeness. Act as a new developer who has never seen this project, attempting to follow every instruction literally.

DOCUMENTATION TYPE: [README / API reference / onboarding guide / architecture docs]
PROJECT: [brief description of what the project does]

DOCUMENTATION:
[paste the documentation content]

SOURCE CODE (for verification):
[paste relevant code that the docs describe]

Evaluate across these dimensions:

1. **Accuracy**
   - Do code examples compile and run without modifications?
   - Do API descriptions match the actual function signatures and return types?
   - Are installation steps current (correct package manager, versions, commands)?
   - Are configuration examples consistent with .env.example?

2. **Completeness**
   - Can a new developer go from zero to running the project using only this doc?
   - Are prerequisites listed (Node version, system dependencies, accounts needed)?
   - Are error scenarios documented ("if you see X error, do Y")?
   - Are all public APIs documented?

3. **Organization**
   - Is there a clear structure (quick start → detailed guides → API reference)?
   - Are headings descriptive and scannable?
   - Is the reading order logical (setup before usage, basics before advanced)?
   - Is a table of contents provided for long documents?

4. **Code Examples**
   - Does every API method have at least one usage example?
   - Are examples copy-pasteable (complete, not fragments)?
   - Do examples show common use cases AND edge cases?
   - Are example outputs/responses included?

5. **Maintenance**
   - Is there a "last updated" indicator?
   - Are deprecated features marked clearly?
   - Are there links to outdated external resources?
   - Is documentation generated from source (JSDoc/TSDoc) or manually maintained?

For each issue, provide:
- **Section**: Where in the docs
- **Severity**: misleading (will cause errors) / incomplete (leaves gaps) / stale / improvement
- **Problem**: What a new reader would experience
- **Fix**: Corrected documentation text

Example Output

## Documentation Review: 5 issues found

### Misleading: Wrong Installation Command
Section: Getting Started, step 2
Doc says: `npm install` — but project uses pnpm (pnpm-lock.yaml present).
Impact: npm install creates conflicting lock file and may resolve different versions.
Fix: `pnpm install`

### Incomplete: Missing Environment Setup
Section: Getting Started
Doc jumps from "clone the repo" to "run the dev server" — no mention of:
- Creating .env.local from .env.example
- Required API keys (STRIPE_KEY, DATABASE_URL)
- Database setup (docker-compose up for PostgreSQL)
Fix: Add "Environment Setup" section between clone and run steps.

### Stale: API Example Uses Deprecated Method
Section: Authentication API
Doc shows: `auth.login(email, password)` — actual code requires `auth.signIn({ email, password })`
Fix: Update to match current API signature.

When to Use

Run this when onboarding new team members, after major refactors, or before open-sourcing a project. Particularly valuable when documentation was written during initial development and has not been updated since. Use it quarterly as a documentation freshness audit.

Pro Tips

• Include the source code — documentation accuracy can only be verified against the actual implementation. Always provide both.
• Test the quick start literally — the fastest way to find doc bugs is to follow instructions on a clean machine. Ask “Walk through the setup guide step by step and flag every instruction that would fail.”
• Generate from code — follow up with “Generate JSDoc/TSDoc comments for all exported functions, then generate API reference documentation from them.”