Code Documentation

Code Documentation

Overview

Generate professional, comprehensive documentation for software projects, codebases, libraries, and APIs. Follows best practices from React, Django, Stripe, Kubernetes to produce accurate, well-structured docs.

When to Use

• User asks to "document", "create docs", or "write documentation" for code
• User requests a README, API reference, or developer guide
• User shares a codebase and wants documentation generated
• User asks to improve or update existing documentation
• User needs architecture documentation with diagrams
• User requests a changelog or migration guide

Workflow

Phase 1: Codebase Analysis

Step 1.1: Project Discovery

# Discover project structure
list_dir(".")
# Read key files
read_file("package.json")  # or pyproject.toml, go.mod, etc.
# Find all source files
bash("find . -name '*.py' -not -path '*/venv/*' -not -path '*/.venv/*' | head -30")

Step 1.2: Code Structure Analysis

# Find entry points
bash("grep -rl 'if __name__' --include='*.py' . | head -10")

# Find API routes/endpoints
bash("grep -rn '@app.route\|@router\.\|def get\|def post' --include='*.py' . | head -20")

# Find exported modules
bash("grep -rn 'export\|module.exports' --include='*.js' --include='*.ts' . | head -20")

# Find classes (for API reference)
bash("grep -rn '^class ' --include='*.py' . | head -20")

Phase 2: Documentation Generation

README.md

# Project Name

> One-line description

## Features
- Feature 1
- Feature 2

## Installation
\`\`\`bash
pip install project-name
\`\`\`

## Quick Start
\`\`\`python
from project import Client
client = Client()
result = client.do_thing()
\`\`\`

## API Reference
### `Client.do_thing(param: str) -> Result`
Description of what this does.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| param | str | Yes | The input |

## Configuration
| Key | Default | Description |
|-----|---------|-------------|

## Contributing
See CONTRIBUTING.md

## License
MIT

API Reference

For each public function/class:

• Signature (parameters, return type)
• Description
• Parameters table
• Return value
• Example usage
• Exceptions raised

Architecture Documentation

• System overview diagram (use architecture-diagram skill)
• Component descriptions
• Data flow
• Key design decisions (ADR format)

Phase 3: Review

• All public APIs documented
• Examples are runnable
• Installation instructions tested
• No broken links
• Language-appropriate conventions (docstrings, JSDoc, GoDoc)
• Architecture diagram included for complex projects

Documentation Conventions by Language

Changelog Generation

# From git log
bash("git log --oneline --no-decorate v1.0.0..HEAD | head -50")

# Generate changelog from commits
bash("git log v1.0.0..HEAD --pretty=format:'- %s (%h)' --no-merges")

Pitfalls

• Stale docs: documentation must match code. If code changed, docs must update. Note the commit/version the docs were generated from.
• No examples: documentation without runnable examples is useless. Always include copy-pasteable examples.
• Over-documenting internals: document public API, not implementation details. Internal code should have inline comments, not API docs.
• No table of contents: for long docs, include a TOC with anchor links.
• Missing prerequisites: list all dependencies, environment requirements, and minimum versions.