codebase-documenter

Use for:

• Writing or updating README files
• Creating architecture documentation
• Adding meaningful code comments
• Documenting APIs and endpoints
• Creating getting-started guides
• Explaining project structure

Don't use when:

• Code review → use generic-code-reviewer
• UX design decisions → use generic-ux-designer
• Adding code features → use generic-feature-developer

1. Start with "Why" - Explain purpose before implementation
2. Progressive Disclosure - Simple to complex
3. Provide Context - Why code exists, not just what it does
4. Include Examples - Concrete usage for every concept
5. Assume No Prior Knowledge - Define terms, avoid jargon
6. Visual Aids - Diagrams, file trees, flowcharts
7. Quick Wins - Get something running in 5 minutes

1. Analyze - Entry points, dependencies, core concepts, configuration
2. Choose Type - README → Architecture → API → Comments
3. Generate - Use templates, customize for project
4. Verify - Read as beginner, test examples

README (Project Entry Point)

```markdown

# Project Name

[1-2 sentence explanation]

[< 5 minute setup]

[Visual file tree]

[Core abstractions]

[Step-by-step guides]

```

Architecture Documentation

```markdown

# Architecture Overview

[High-level diagram]

[How data moves through system]

[Why certain choices were made]

[Where to add new features]

```

Code Comments

```typescript

// ✅ GOOD - Explains WHY and context

// IndexedDB quota check: Prevents silent failures when storage is full.

// Without this, writes fail with cryptic QuotaExceededError.

if (quota.percentUsed > 80) showStorageWarning();

// ❌ BAD - Just repeats what code does

// Check if quota is over 80

```

API Documentation

```markdown

What It Does

[Plain-English purpose]

Request/Response

[JSON examples]

Common Errors

[Error codes and meanings]

```

File Tree

```

project/

├── src/ # Source code

│ ├── components/ # Reusable UI

│ ├── services/ # Business logic

│ └── types/ # TypeScript types

├── tests/ # Test files

└── package.json # Dependencies

```

Data Flow

```

User Request Flow:

1. User submits → 2. Validation → 3. API → 4. Database → 5. Response

[1] components/Form.tsx

↓ validates

[2] services/validation.ts

↓ calls API

[3] services/api.ts

↓ queries

[4] Database

↓ returns

[5] Form.tsx (updates UI)

```

Design Decision (ADR)

```markdown

Decision: [What we chose]

Context: [Why we needed to choose]

Reasoning: [Why this option]

Trade-offs: [What we gave up]

```

Before Publishing

• [ ] Quick start works in < 5 minutes
• [ ] Code examples are copy-pasteable
• [ ] File paths are accurate
• [ ] Links work
• [ ] Jargon is defined
• [ ] Diagrams are included for complex flows

Common Mistakes to Avoid

• Assuming reader knows the codebase
• Outdated code examples
• Missing prerequisites
• No visual aids for complex systems
• Explaining "what" without "why"

After writing documentation:

1. Fresh Eyes Test - Read as if you've never seen the codebase
2. Run Examples - Copy-paste and verify they work
3. Check Links - All internal/external links resolve
4. Beginner Review - Would a new developer understand?
5. Update Check - Does it reflect current code?

• [Code Review Standards](../_shared/CODE_REVIEW_STANDARDS.md) - Documentation quality
• Project CLAUDE.md - Documentation rules