Documentation Skill

When writing or improving documentation, follow these principles:

1. Know Your Audience

• README: New developers evaluating or onboarding to the project.
• API docs: Developers integrating with the API.
• Architecture docs: Team members understanding system design.
• Inline comments: Future maintainers (including yourself in 6 months).

2. README Structure

A good README answers these questions in order:

1. What is this? One paragraph. What problem does it solve?
2. Quick start: The fastest path from zero to working. Copy-pasteable commands.
3. Installation: Prerequisites, install steps, configuration.
4. Usage: Common use cases with code examples.
5. API reference: If small enough; otherwise link to generated docs.
6. Configuration: All options with defaults and descriptions.
7. Contributing: How to set up dev environment, run tests, submit changes.
8. License: One line.

3. API Documentation

For each endpoint, function, or method:

### functionName(param1, param2, options?)

Brief description of what it does.

**Parameters:**
- `param1` (string, required) — What this parameter controls.
- `param2` (number, optional, default: 10) — What this parameter controls.
- `options.verbose` (boolean, default: false) — Enable verbose output.

**Returns:** `Promise<Result>` — Description of the return value.

**Throws:**
- `ValidationError` — When input is invalid.
- `NotFoundError` — When the resource doesn't exist.

**Example:**
```ts
const result = await functionName("input", 5);

```

4. Architecture Documentation

• Start with a high-level diagram (Mermaid, ASCII, or image).
• Describe each component’s responsibility in one sentence.
• Document data flow for the most important operations.
• List key design decisions and their rationale.
• Note known limitations and planned improvements.

5. Inline Comments

Write comments that explain why, not what:

• ✅ // Retry 3 times because the upstream API has transient 503s during deploys
• ❌ // Retry 3 times
• ✅ // Sort descending so the most recent entry is first for the dashboard
• ❌ // Sort the array

Never comment obvious code. If code needs a comment to explain what it does, refactor the code to be self-explanatory first.

6. Quality Checklist

Before finalizing documentation:

• All code examples compile and run.
• No broken links.
• Consistent formatting and terminology.
• No outdated information from previous versions.
• Spelling and grammar checked.
• Table of contents for documents longer than 3 sections.