/documentation

name: documentation
description: Use when shipping features with public interfaces that lack docs, generating documentation, updating README files, writing API docs, creating architecture documentation, or when documentation is incomplete or outdated. Also use when adding breaking changes, implementing complex algorithms, or before shipping any phase — if a public function lacks a docstring, this skill applies.

<!-- TOKEN BUDGET: 290 lines / ~870 tokens -->

Documentation Generation

<activation>

When to Use

• After implementing new features with public interfaces
• When making breaking changes
• When adding complex algorithms or business logic
• Before shipping a phase or milestone
• When documentation is flagged as incomplete
• When conversation mentions: document, README, API docs, changelog

Natural Language Triggers

• "document this", "write docs", "update README", "API docs", "needs documentation"

</activation>

When NOT to Use

• Internal helper functions not part of any public interface
• Generated code (auto-generated files, protobuf outputs, migrations)
• Throwaway prototypes, scripts, or spike code
• Trivial one-liners where the code IS the documentation

Generate accurate, useful documentation that serves its audience. API docs for developers, guides for users, architecture docs for maintainers.

**The documenter agent references this skill for systematic documentation generation.**

<instructions>

Documentation Types

1. Code Documentation (Inline)

Document non-obvious code for developers reading the implementation.

**What to document:**

• Complex algorithms and business logic
• Non-obvious design decisions
• Workarounds and edge cases
• Performance considerations

**What NOT to document:** Anything a competent developer can understand by reading the code itself.

**HOW — step by step:** 1. Read the function/class from the consumer's perspective 2. Ask: "Would a senior dev understand WHY this exists?" If no, add a comment 3. For public functions: write docstring with parameters, returns, exceptions, and at least one example 4. For classes: write purpose + responsibilities in one paragraph 5. For modules: write one-line overview at the top

**Format:** Docstrings with parameters, returns, exceptions, and examples for functions. Purpose and responsibilities for classes. Overview for modules.

2. API Documentation

Help developers use public interfaces correctly.

**HOW — step by step:** 1. List every public endpoint/function in the module 2. For each: write description (one sentence max), then parameters with types + constraints 3. Document return values and all error conditions 4. Write at least one realistic example per function 5. For HTTP APIs: add authentication/authorization requirements 6. Run every example to verify it works

**Per endpoint/function:**

• Description (one sentence)
• Parameters with types and constraints
• Return values
• Error conditions
• At least one realistic example
• Authentication/authorization requirements (for APIs)

**Checklist:**

• [ ] All public functions/endpoints documented
• [ ] Parameter types and constraints specified
• [ ] Return values described
• [ ] Error conditions documented
• [ ] At least one example per function
• [ ] Auth requirements noted for HTTP APIs

3. Architecture Documentation

Help developers understand system design and make consistent changes.

**HOW — step by step:** 1. Draw (or describe) the component diagram first — boxes and arrows 2. For each component: one sentence on what it does, one on what it does NOT do 3. Document data flow: where data enters, how it transforms, where it exits 4. For each key design decision: record the decision, why it was chosen, alternatives rejected 5. List all external dependencies with version constraints 6. Document deployment topology (single box, microservices, cloud regions)

**Architecture doc example:**

## Components

| Component | Responsibility | Does NOT handle |
|-----------|---------------|-----------------|
| API Gateway | Route requests, auth validation | Business logic |
| User Service | CRUD user accounts | Billing, permissions |
| Notification Worker | Send emails/SMS async | Template rendering |

## Key Decision: Event-Driven vs. Synchronous

**Decision:** Use async events for cross-service communication
**Rationale:** Decouples services; allows independent scaling
**Rejected:** Direct HTTP calls — too much coupling, cascading failures

**Checklist:**

• [ ] System overview exists
• [ ] Component responsibilities documented
• [ ] Data flow explained
• [ ] Design decisions recorded with rationale

4. User Documentation

Help end-users accomplish tasks.

**HOW — step by step:** 1. Identify the user's goal (not the feature name) 2. List prerequisites (what must already be installed/configured) 3. Write steps numbered sequentially — one action per step 4. Show expected output after each step 5. Add a "What if it fails?" section for common errors 6. Test the guide yourself from scratch

**User guide example:**

## How to Set Up Webhook Notifications

**Prerequisites:** Admin account, HTTPS endpoint that accepts POST requests

1. Go to Settings → Integrations → Webhooks
2. Click **Add Webhook**
3. Enter your endpoint URL (must start with `https://`)
4. Select events to subscribe to (e.g., `user.created`, `order.paid`)
5. Click **Save** — a test ping is sent to your endpoint immediately

**Expected:** Your endpoint receives a `POST` with `{"event": "test.ping"}`

**If it fails:** Check that your endpoint returns HTTP 200. Non-200 responses
are retried 3 times then marked failed.

**Types:**

• **Getting Started:** Installation, first-run config, hello world, next steps
• **How-To Guides:** Goal-oriented, step-by-step, prerequisites, expected outcome
• **Tutorials:** Learning-oriented, guided, explains why not just how
• **Reference:** CLI commands, config options, env vars, troubleshooting

**Check