Documentation Generation Skill

Documentation Generation

Generate quality documentation that stays in sync with code. From READMEs to API docs to architecture documentation.

Quick Reference

| Doc Type | Primary File | When to Use | |----------|--------------|-------------| | Project README | README.md | New project, major updates | | API Documentation | JSDoc/docstrings | New functions, API changes | | OpenAPI/Swagger | openapi.yaml | REST API documentation | | Architecture | ARCHITECTURE.md | System design, major components | | Change Log | CHANGELOG.md | Each release | | Migration Guide | MIGRATION.md | Breaking changes |

Documentation Principles

1. Document the Why, Not Just the What

// Bad: Documents what the code does (obvious from code)
// Increments counter by 1

// Good: Documents why
// Prevents race condition by using atomic increment

2. Keep Docs Close to Code

| Pattern | Benefit | |---------|---------| | JSDoc above functions | Updates when code changes | | README.md in package | Visible in package managers | | Inline comments | Context at point of use |

3. Use Examples Liberally

Every API function should have at least one working example. Examples are:

Tested implicitly when code runs
More useful than prose descriptions
Easier to keep up to date

README Structure

A good README follows this structure:

# Project Name

One-sentence description of what this does.

## Quick Start

\`\`\`bash
npm install package-name
\`\`\`

\`\`\`typescript
import { main } from 'package-name';
main();
\`\`\`

## Features

- Feature 1 - brief description
- Feature 2 - brief description

## Installation

Detailed installation instructions.

## Usage

### Basic Usage
...

### Advanced Usage
...

## API Reference

Link to detailed API docs or inline reference.

## Configuration

Environment variables, config files.

## Contributing

How to contribute.

## License

License information.

README Anti-Patterns

| Avoid | Instead | |-------|---------| | Wall of text | Short paragraphs, bullet points | | Outdated examples | Use tested code snippets | | Missing quick start | Add minimal working example | | No installation | Include all setup steps |

Inline Documentation

JSDoc for TypeScript/JavaScript

/**
 * Calculates the total price including tax.
 *
 * @param items - Array of items with price property
 * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
 * @returns Total price with tax applied
 *
 * @example
 * ```typescript
 * const items = [{ price: 10 }, { price: 20 }];
 * calculateTotal(items, 0.08); // 32.40
 * ```
 *
 * @throws {Error} If taxRate is negative
 */
function calculateTotal(items: Item[], taxRate: number): number {
  // implementation
}

Python Docstrings

def calculate_total(items: list[Item], tax_rate: float) -> float:
    """Calculate the total price including tax.

    Args:
        items: List of items with price attribute.
        tax_rate: Tax rate as decimal (e.g., 0.08 for 8%).

    Returns:
        Total price with tax applied.

    Raises:
        ValueError: If tax_rate is negative.

    Example:
        >>> items = [Item(price=10), Item(price=20)]
        >>> calculate_total(items, 0.08)
        32.40
    """

When to Comment

| Do Comment | Don't Comment | |------------|---------------| | Complex algorithms | Obvious operations | | Business rules | What the code literally does | | Non-obvious side effects | Self-explanatory names | | Performance optimizations | Getters/setters | | Workarounds and hacks | Every line |

Workflow: Document New Project

Prerequisites

[ ] Project structure exists
[ ] Main functionality works
[ ] Package.json/pyproject.toml configured

Steps

Create README.md
- [ ] Add project name and description
- [ ] Write quick start with minimal example
- [ ] Document installation steps
- [ ] Add usage examples
Add API Documentation
- [ ] Add JSDoc/docstrings to public functions
- [ ] Include @example for each function
- [ ] Document parameters and return types
- [ ] Note any thrown exceptions
Create Architecture Doc (if needed)
- [ ] Diagram main components
- [ ] Explain data flow
- [ ] Document key decisions
Initialize Changelog
- [ ] Create CHANGELOG.md
- [ ] Add initial version entry

Validation

[ ] README has working quick start
[ ] All public APIs documented
[ ] Examples are runnable
[ ] No broken links

Workflow: Update Existing Documentation

Steps

Identify Stale Docs
- [ ] Check README against current behavior
- [ ] Verify API docs match signatures
- [ ] Test example code snippets
Update Documentation
- [ ] Fix outdated examples
- [ ] Update API references
- [ ] Add missing sections
Validate
- [ ] Run example code
- [ ] Check all links work
- [ ] Review for consistency

Workflow: Generate API Docs

For TypeScript (TypeDoc)

# Install
bun add -d typedoc

# Generate
bunx typedoc --out docs src/index.ts

For Python (Sphinx)

# Install
pip install sphinx sphinx-autodoc-typehints

# Generate
sphinx-apidoc -o docs/api src/
sphinx-build -b html docs docs/_build

For OpenAPI

See API-DOCS.md for detailed OpenAPI generation patterns.

Keeping Docs in Sync

Automated Approaches

| Approach | Tool | Use Case | |----------|------|----------| | TypeDoc | TypeScript | Generate from JSDoc | | Sphinx | Python | Generate from docstrings | | OpenAPI Generator | REST | Generate from spec | | Storybook | React | Component documentation |

Manual Checklist

Add to PR template:

## Documentation
- [ ] README updated (if public API changed)
- [ ] JSDoc/docstrings added for new functions
- [ ] CHANGELOG updated
- [ ] Migration guide updated (if breaking change)

Documentation Tests

// In test file
import { exampleCode } from '../docs/examples';

test('documentation examples work', async () => {
  // Run the example code from docs
  const result = await exampleCode();
  expect(result).toBeDefined();
});

Common Documentation Tasks

Add JSDoc to Existing Code

// Before
function processData(data, options) {
  // ...
}

// After
/**
 * Processes raw data according to specified options.
 *
 * @param data - Raw data to process
 * @param options - Processing configuration
 * @param options.validate - Whether to validate input (default: true)
 * @param options.transform - Transform function to apply
 * @returns Processed data object
 *
 * @example
 * ```typescript
 * const result = processData(rawData, { validate: true });
 * ```
 */
function processData(data: RawData, options: ProcessOptions): ProcessedData {
  // ...
}

Generate README from Template

For a TypeScript library:

# {package-name}

{one-line-description}

[![npm version](https://badge.fury.io/js/{package-name}.svg)](https://www.npmjs.com/package/{package-name})

## Installation

\`\`\`bash
npm install {package-name}
# or
bun add {package-name}
\`\`\`

## Quick Start

\`\`\`typescript
import { main } from '{package-name}';

const result = main();
console.log(result);
\`\`\`

## API

### `main(options?)`

Main entry point.

**Parameters:**
- `options.debug` (boolean): Enable debug mode

**Returns:** Result object

## License

MIT

Debugging Documentation Issues

| Issue | Solution | |-------|----------| | Outdated examples | Set up doc tests | | Broken links | Use relative links, add link checker | | Missing docs | Add to PR checklist | | Inconsistent style | Use doc linter (markdownlint) |

Reference Files

| File | Contents | |------|----------| | README-PATTERNS.md | README generation, project documentation patterns | | API-DOCS.md | API documentation, JSDoc, docstrings, OpenAPI | | MAINTENANCE.md | Keeping docs up to date, validation strategies |

Agent Skills: Documentation Generation

Skill Files