name: document
description: "Generate and maintain technical documentation. Creates README files, API documentation, code comments, architecture docs, and user guides. Ensures documentation stays accurate, accessible, and useful. Follows documentation standards and best practices for different audiences."
phase: DOCUMENT
category: core
version: "1.0.0"
depends_on: ["implement"]
tags: [documentation, core-workflow]

Document

Generate and maintain technical documentation.

When to Use

• New project — Create initial documentation suite
• New feature — Document new functionality
• API changes — Update API documentation
• Onboarding — Create guides for new team members
• Release — Generate changelogs and release notes
• When you say: "document this", "write docs for", "create a README"

Reference Requirements

MUST read before applying this skill:

Read if applicable:

Verification: Ensure README.md exists with quick start that actually works.

Required Deliverables

Core Concept

Document answers: "How do I explain this clearly to someone who isn't me?"

Good documentation is:
- Accurate — Matches the actual code/system
- Accessible — Written for the target audience
- Actionable — Readers can accomplish their goals
- Maintained — Updated when things change

Documentation is NOT:
- Comments on every line of code
- Duplicating what the code already says
- A one-time task (it requires maintenance)

Documentation Types

The Documentation Process

┌─────────────────────────────────────────────────────────┐
│                DOCUMENTATION PROCESS                    │
│                                                         │
│  1. IDENTIFY AUDIENCE                                   │
│     └─→ Who will read this? What do they need?          │
│                                                         │
│  2. DETERMINE SCOPE                                     │
│     └─→ What needs documenting? What's out of scope?    │
│                                                         │
│  3. GATHER INFORMATION                                  │
│     └─→ Code, specs, interviews, existing docs          │
│                                                         │
│  4. STRUCTURE CONTENT                                   │
│     └─→ Organize for reader's journey                   │
│                                                         │
│  5. WRITE DRAFT                                         │
│     └─→ Clear, concise, example-rich                    │
│                                                         │
│  6. REVIEW & VERIFY                                     │
│     └─→ Technically accurate? Readable?                 │
│                                                         │
│  7. PUBLISH & MAINTAIN                                  │
│     └─→ Keep it current, remove stale content           │
└─────────────────────────────────────────────────────────┘

Step 1: Identify Audience

Audience Analysis

Writing for Your Audience

## For New Developers
- Assume no prior context
- Start with "what is this?"
- Provide copy-paste examples
- Link to prerequisites

## For Experienced Developers
- Skip the basics
- Provide complete reference
- Include edge cases
- Link to source code

## For End Users
- Use their language, not technical jargon
- Focus on tasks, not features
- Include screenshots
- Provide troubleshooting

Step 2: Determine Scope

Documentation Inventory

## Documentation Needed

### Essential (Must Have)
- [ ] README with quick start
- [ ] Installation instructions
- [ ] Basic usage examples
- [ ] Environment variables reference

### Important (Should Have)
- [ ] API documentation
- [ ] Architecture overview
- [ ] Contributing guide
- [ ] Troubleshooting guide

### Nice to Have
- [ ] Tutorials for common tasks
- [ ] Video walkthroughs
- [ ] Migration guides
- [ ] Performance tuning guide

What NOT to Document

• Implementation details that change frequently
• Things the code clearly expresses
• Obvious type information
• Internal helper functions

Step 3: Gather Information

Information Sources

Extraction Techniques

# Extract function signatures
grep -r "export function\|export const" src/

# Find public APIs
grep -r "@public\|@api" src/

# Extract environment variables
grep -r "process\.env\." src/ | grep -oE "process\.env\.[A-Z_]+" | sort -u

# Find TODOs and FIXMEs
grep -r "TODO\|FIXME" src/

Step 4: Structure Content

Information Architecture

┌─────────────────────────────────────────────────────────┐
│                    DOCUMENTATION MAP                    │
│                                                         │
│  Landing (README)                                       │
│  ├── What is this?                                      │
│  ├── Quick Start ←── Most users start here              │
│  └── Links to deeper docs                               │
│                                                         │
│  Getting Started                                        │
│  ├── Installation                                       │
│  ├── Configuration                                      │
│  └── First steps                                        │
│                                                         │
│  Guides (Task-oriented)                                 │
│  ├── How to do X                                        │
│  ├── How to do Y                                        │
│  └── How to do Z                                        │
│                                                         │
│  Reference (Information-oriented)                       │
│  ├── API Reference                                      │
│  ├── Configuration Reference                            │
│  └── CLI Reference                                      │
│                                                         │
│  Explanation (Understanding-oriented)                   │
│  ├── Architecture                                       │
│  ├── Design decisions                                   │
│  └── Concepts                                           │
│                                                         │
└─────────────────────────────────────────────────────────┘

The Diátaxis Framework

Step 5: Write Draft

Writing Principles

Be concise. Remove unnecessary words.

# Bad
In order to install the application, you will need to run the following command:

# Good
Install with:

Use active voice.

# Bad
The configuration file should be created by the user.

# Good
Create a configuration file.

Front-load important information.

# Bad
After completing the installation process and configuring your environment 
variables, you can start the server by running npm start.

# Good
Run `npm start` to start the server.

Prerequisites: Install dependencies and configure environment variables first.

Show, don't just tell.

# Bad
The API returns user data.

# Good
The API returns user data:
```json
{
  "id": "123",
  "name": "Alice",
  "email": "[email protected]"
}

→ See `references/writing-guidelines.md`

## README Template

```markdown
# Project Name

One-line description of what this project does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Quick Start

```bash
# Install
npm install project-name

# Configure
cp .env.example .env

# Run
npm start

Documentation

• Installation Guide
• API Reference
• Configuration
• Contributing

Requirements

• Node.js 18+
• PostgreSQL 14+

License

MIT

→ See `references/readme-templates.md`

## API Documentation

### Endpoint Documentation

```markdown
## Create User

Creates a new user account.

### Request

```http
POST /api/users
Content-Type: application/json
Authorization: Bearer <token>

Body

Example

{
  "email": "[email protected]",
  "name": "Alice Smith",
  "role": "admin"
}

Response

Success (201 Created)

{
  "data": {
    "id": "usr_123",
    "email": "[email protected]",
    "name": "Alice Smith",
    "role": "admin",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Errors

→ See `references/api-documentation.md`

## Code Comments

### When to Comment

| Comment | Don't Comment |
|---------|---------------|
| **Why** something is done | **What** code does (code should be clear) |
| Complex algorithms | Simple operations |
| Non-obvious side effects | Type information (use types) |
| Workarounds and their reasons | Obvious function behavior |
| Public API contracts | Implementation details |

### Comment Styles

```typescript
/**
 * Calculates the optimal shipping route for an order.
 * 
 * Uses Dijkstra's algorithm with warehouse proximity weighting.
 * Falls back to nearest warehouse if no optimal route found.
 * 
 * @param order - The order to ship
 * @param warehouses - Available warehouses with inventory
 * @returns The selected warehouse and estimated delivery date
 * @throws {NoInventoryError} If no warehouse has sufficient inventory
 * 
 * @example
 * const route = await calculateRoute(order, warehouses);
 * console.log(route.warehouse.name, route.estimatedDelivery);
 */
export async function calculateShippingRoute(
  order: Order,
  warehouses: Warehouse[]
): Promise<ShippingRoute> {
  // ...
}

// BAD: Comments that repeat the code
// Increment counter by 1
counter++;

// GOOD: Comments that explain why
// Skip the first item because it's the header row
for (let i = 1; i < rows.length; i++) {
  // ...
}

// GOOD: Warning about non-obvious behavior
// WARNING: This function mutates the input array for performance.
// Clone the array first if you need to preserve the original.
function sortInPlace(items: Item[]): void {
  // ...
}

→ See references/code-comments.md

Architecture Documentation

Architecture Overview

# Architecture Overview

## System Context

[Diagram showing system and external actors]

## High-Level Architecture

[Diagram showing major components]

## Key Design Decisions

| Decision | Rationale | Trade-offs |
|----------|-----------|------------|
| PostgreSQL for primary data | ACID compliance, team expertise | Scaling requires more effort |
| Redis for caching | Sub-ms latency, built-in expiration | Additional infrastructure |
| Event-driven for async | Decoupling, resilience | Eventual consistency |

## Data Flow

[Diagram showing how data moves through system]

## Technology Stack

| Layer | Technology | Purpose |
|-------|------------|---------|
| Frontend | React | User interface |
| API | Node.js/Express | REST API |
| Database | PostgreSQL | Primary data store |
| Cache | Redis | Session, hot data |
| Queue | SQS | Async processing |

## Further Reading

- [ADR-001: Database Selection](adrs/001-database.md)
- [ADR-002: Authentication Approach](adrs/002-auth.md)

→ See references/architecture-docs.md

Runbooks

Runbook Template

# Runbook: [Issue Name]

## Overview
Brief description of the issue and its impact.

## Symptoms
- Symptom 1 (what you'll see)
- Symptom 2
- Related alerts: [Alert names]

## Impact
- User impact: [Description]
- Business impact: [Description]
- Severity: [P1/P2/P3]

## Quick Diagnosis

```bash
# Check service health
curl https://api.example.com/health

# Check recent logs
kubectl logs -l app=api --tail=100

# Check metrics
# [Link to dashboard]

Resolution Steps

Step 1: [First action]

[Command to run]

Expected output: [What you should see]

Step 2: [Second action]

[Instructions]

Step 3: Verify fix

# Verify service is healthy
curl https://api.example.com/health

Escalation

If the above steps don't resolve the issue:
1. Page the on-call engineer: [Contact]
2. Escalate to: [Team/Person]

Post-Incident

• [ ] Create incident ticket
• [ ] Update this runbook if needed
• [ ] Schedule post-mortem if P1/P2

Related

• [Link to architecture docs]
• [Link to related runbooks]

→ See `references/runbook-templates.md`

## Changelog & Release Notes

### Changelog Format

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New feature X for doing Y

### Changed
- Improved performance of Z by 50%

### Fixed
- Bug where A happened when B

## [2.1.0] - 2024-01-15

### Added
- User authentication via OAuth (#123)
- Rate limiting on API endpoints (#145)
- Dark mode support (#156)

### Changed
- Upgraded Node.js to v20 (#167)
- Improved error messages for validation errors

### Fixed
- Memory leak in long-running connections (#178)
- Incorrect timezone handling in reports (#182)

### Security
- Updated dependencies to patch CVE-2024-1234

### Deprecated
- The `legacyAuth` option will be removed in v3.0

## [2.0.0] - 2024-01-01

### Breaking Changes
- Renamed `userId` to `user_id` in API responses
- Minimum Node.js version is now 18

### Migration Guide
See [MIGRATION.md](MIGRATION.md) for upgrade instructions.

→ See references/changelog-guide.md

Documentation Maintenance

Keeping Docs Current

Documentation Review Checklist

## Periodic Review Checklist

### Accuracy
- [ ] Code examples still work
- [ ] Screenshots match current UI
- [ ] Links are not broken
- [ ] Version numbers are current

### Completeness
- [ ] New features are documented
- [ ] Deprecated features are marked
- [ ] Common questions are answered

### Quality
- [ ] No spelling/grammar errors
- [ ] Consistent terminology
- [ ] Clear and concise
- [ ] Properly formatted

Stale Documentation Indicators

• 🚩 Last updated >6 months ago
• 🚩 References old versions
• 🚩 Broken code examples
• 🚩 Screenshots don't match UI
• 🚩 "TODO" or "Coming soon" sections
• 🚩 References removed features

Documentation Tools

Relationship to Other Skills

Key Principles

Write for your reader. Not for yourself.

Less is more. Concise docs get read; verbose docs get skipped.

Show examples. One good example is worth paragraphs of explanation.

Keep it current. Outdated docs are worse than no docs.

Make it findable. Good docs that can't be found are useless.

Test your docs. Follow your own instructions. Do they work?

References

• references/readme-templates.md: README templates for different project types
• references/api-documentation.md: API documentation patterns and examples
• references/code-comments.md: When and how to comment code
• references/architecture-docs.md: Architecture documentation templates
• references/runbook-templates.md: Operational runbook templates
• references/writing-guidelines.md: Technical writing best practices
• references/changelog-guide.md: Changelog and release notes guide