codebase-documenter

$28

1. README Documentation

When to create: For project root directories, major feature modules, or standalone components.

Structure to follow:

# Project Name

## What This Does

[1-2 sentence plain-English explanation]

## Quick Start

[Get users running the project in < 5 minutes]

## Project Structure

[Visual file tree with explanations]

## Key Concepts

[Core concepts users need to understand]

## Common Tasks

[Step-by-step guides for frequent operations]

## Troubleshooting

[Common issues and solutions]

Best practices:

• Lead with the project's value proposition

• Include setup instructions that actually work (test them!)

• Provide a visual overview of the project structure

• Link to deeper documentation for advanced topics

• Keep the root README focused on getting started

2. Architecture Documentation

When to create: For projects with multiple modules, complex data flows, or non-obvious design decisions.

Structure to follow:

# Architecture Overview

## System Design

[High-level diagram and explanation]

## Directory Structure

[Detailed breakdown with purpose of each directory]

## Data Flow

[How data moves through the system]

## Key Design Decisions

[Why certain architectural choices were made]

## Module Dependencies

[How different parts interact]

## Extension Points

[Where and how to add new features]

Best practices:

• Use diagrams to show system components and relationships

• Explain the "why" behind architectural decisions

• Document both the happy path and error handling

• Identify boundaries between modules

• Include visual file tree structures with annotations

3. Code Comments

When to create: For complex logic, non-obvious algorithms, or code that requires context.

Annotation patterns:

Function/Method Documentation:

/**

 * Calculates the prorated subscription cost for a partial billing period.

 *

 * Why this exists: Users can subscribe mid-month, so we need to charge

 * them only for the days remaining in the current billing cycle.

 *

 * @param {number} fullPrice - The normal monthly subscription price

 * @param {Date} startDate - When the user's subscription begins

 * @param {Date} periodEnd - End of the current billing period

 * @returns {number} The prorated amount to charge

 *

 * @example

 * // User subscribes on Jan 15, period ends Jan 31

 * calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))

 * // Returns: 16.13 (17 days out of 31 days)

 */

Complex Logic Documentation:

# Why this check exists: The API returns null for deleted users,

# but empty string for users who never set a name. We need to

# distinguish between these cases for the audit log.

if user_name is None:

    # User was deleted - log this as a security event

    log_deletion_event(user_id)

elif user_name == "":

    # User never completed onboarding - safe to skip

    continue

Best practices:

• Explain "why" not "what" - the code shows what it does

• Document edge cases and business logic

• Add examples for complex functions

• Explain parameters that aren't self-explanatory

• Note any gotchas or counterintuitive behavior

4. API Documentation

When to create: For any HTTP endpoints, SDK methods, or public interfaces.

Structure to follow:

## Endpoint Name

### What It Does

[Plain-English explanation of the endpoint's purpose]

### Endpoint

`POST /api/v1/resource`

### Authentication

[What auth is required and how to provide it]

### Request Format

[JSON schema or example request]

### Response Format

[JSON schema or example response]

### Example Usage

[Concrete example with curl/code]

### Common Errors

[Error codes and what they mean]

### Related Endpoints

[Links to related operations]

Best practices:

• Provide working curl examples

• Show both success and error responses

• Explain authentication clearly

• Document rate limits and constraints

• Include troubleshooting for common issues

Documentation Workflow

Step 1: Analyze the Codebase

Before writing documentation:

• Identify entry points - Main files, index files, app initialization

• Map dependencies - How modules relate to each other

• Find core concepts - Key abstractions users need to understand

• Locate configuration - Environment setup, config files

• Review existing docs - Build on what's there, don't duplicate

Step 2: Choose Documentation Type

Based on user request and codebase analysis:

• New project or missing README → Start with README documentation

• Complex architecture or multiple modules → Create architecture documentation

• Confusing code sections → Add inline code comments

• HTTP/API endpoints → Write API documentation

• Multiple types needed → Address in order: README → Architecture → API → Comments

Step 3: Generate Documentation

Use the templates from assets/templates/ as starting points:

• assets/templates/README.template.md - For project READMEs

• assets/templates/ARCHITECTURE.template.md - For architecture docs

• assets/templates/API.template.md - For API documentation

Customize templates based on the specific codebase:

• Fill in project-specific information - Replace placeholders with actual content

• Add concrete examples - Use real code from the project

• Include visual aids - Create file trees, diagrams, flowcharts

• Test instructions - Verify setup steps actually work

• Link related docs - Connect documentation pieces together

Step 4: Review for Clarity

Before finalizing documentation:

• Read as a beginner - Does it make sense without project context?

• Check completeness - Are there gaps in the explanation?

• Verify examples - Do code examples actually work?

• Test instructions - Can someone follow the setup steps?

• Improve structure - Is information easy to find?

Documentation Templates

This skill includes several templates in assets/templates/ that provide starting structures:

Available Templates

• README.template.md - Comprehensive README structure with sections for quick start, project structure, and common tasks

• ARCHITECTURE.template.md - Architecture documentation template with system design, data flow, and design decisions

• API.template.md - API endpoint documentation with request/response formats and examples

• CODE_COMMENTS.template.md - Examples and patterns for effective inline documentation

Using Templates

• Read the appropriate template from assets/templates/

• Customize for the specific project - Replace placeholders with actual information

• Add project-specific sections - Extend the template as needed

• Include real examples - Use actual code from the codebase

• Remove irrelevant sections - Delete parts that don't apply

Best Practices Reference

For detailed documentation best practices, style guidelines, and advanced patterns, refer to:

• references/documentation_guidelines.md - Comprehensive style guide and best practices

• references/visual_aids_guide.md - How to create effective diagrams and file trees

Load these references when:

• Creating documentation for complex enterprise codebases

• Dealing with multiple stakeholder requirements

• Needing advanced documentation patterns

• Standardizing documentation across a large project

Common Patterns

Creating File Tree Structures

File trees help new users understand project organization:

project-root/

├── src/                    # Source code

│   ├── components/        # Reusable UI components

│   ├── pages/             # Page-level components (routing)

│   ├── services/          # Business logic and API calls

│   ├── utils/             # Helper functions

│   └── types/             # TypeScript type definitions

├── public/                # Static assets (images, fonts)

├── tests/                 # Test files mirroring src structure

└── package.json           # Dependencies and scripts

Explaining Complex Data Flows

Use numbered steps with diagrams:

User Request Flow:

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

[1] components/UserForm.tsx

    ↓ validates input

[2] services/validation.ts

    ↓ sends to API

[3] services/api.ts

    ↓ queries database

[4] Database (PostgreSQL)

    ↓ returns data

[5] components/UserForm.tsx (updates UI)

Documenting Design Decisions

Capture the "why" behind architectural choices:

## Why We Use Redux

**Decision:** State management with Redux instead of Context API

**Context:** Our app has 50+ components that need access to user

authentication state, shopping cart, and UI preferences.

**Reasoning:**

- Context API causes unnecessary re-renders with this many components

- Redux DevTools helps debug complex state changes

- Team has existing Redux expertise

**Trade-offs:**

- More boilerplate code

- Steeper learning curve for new developers

- Worth it for: performance, debugging, team familiarity

Output Guidelines

When generating documentation:

• Write for the target audience - Adjust complexity based on whether documentation is for beginners, intermediate, or advanced users

• Use consistent formatting - Follow markdown conventions, consistent heading hierarchy

• Provide working examples - Test all code snippets and commands

• Link between documents - Create a documentation navigation structure

• Keep it maintainable - Documentation should be easy to update as code changes

• Add dates and versions - Note when documentation was last updated

Quick Reference

Command to generate README:

"Create a README file for this project that helps new developers get started"

Command to document architecture:

"Document the architecture of this codebase, explaining how the different modules interact"

Command to add code comments:

"Add explanatory comments to this file that help new developers understand the logic"

Command to document API:

"Create API documentation for all the endpoints in this file"