codebase-documenter

Codebase Documenter

Create comprehensive, beginner-friendly documentation for any codebase.

When to Use

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

Core Principles

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

Documentation Workflow

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, check examples against the code by reading

Documentation Types

README (Project Entry Point)

# Project Name

## What This Does

[1-2 sentence explanation]

## Quick Start

[< 5 minute setup]

## Project Structure

[Visual file tree]

## Key Concepts

[Core abstractions]

## Common Tasks

[Step-by-step guides]

Architecture Documentation

# Architecture Overview

## System Design

[High-level diagram]

## Data Flow

[How data moves through system]

## Key Design Decisions

[Why certain choices were made]

## Extension Points

[Where to add new features]

Code Comments

// ✅ 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

## Endpoint: POST /api/resource

### What It Does

[Plain-English purpose]

### Request/Response

[JSON examples]

### Common Errors

[Error codes and meanings]

Visual Patterns

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)

## Why We Use [Technology]

**Decision:** [What we chose]
**Context:** [Why we needed to choose]
**Reasoning:** [Why this option]
**Trade-offs:** [What we gave up]

Documentation Quality Checklist

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"

Verification Workflow

After writing documentation:

1. Fresh Eyes Test - Read as if you've never seen the codebase
2. Check Examples - Read each example against the current code, APIs, and paths it uses
3. Check Links - All internal/external links resolve
4. Beginner Review - Would a new developer understand?
5. Update Check - Does it reflect current code?

See Also

• Code Review Standards - Documentation quality
• Project CLAUDE.md - Documentation rules