xilele777/poirot/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.