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