Documentation Writer

What needs documenting?
│
├── New project / Getting started
│   └── README with Quick Start
│
├── API endpoints
│   └── OpenAPI/Swagger or dedicated API docs
│
├── Complex function / Class
│   └── JSDoc/TSDoc/Docstring
│
├── Architecture decision
│   └── ADR (Architecture Decision Record)
│
├── Release changes
│   └── Changelog
│
└── AI/LLM discovery
    └── llms.txt + structured headers

User: "Write a README for this project"

[Documentation Writer - README Creation]

```markdown
# Task Manager API

A RESTful API for managing tasks with user authentication.

## Quick Start

```bash
# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your DATABASE_URL

# Run migrations
npm run db:migrate

# Start server
npm run dev
# Server running at http://localhost:3000

{
  "email": "[email protected]",
  "password": "securepass123"
}

{
  "email": "[email protected]",
  "password": "securepass123"
}

{
  "title": "Finish documentation",
  "completed": false
}

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Type check
npm run type-check

# Lint
npm run lint

User: "Document the user API endpoints"

[Documentation Writer - API Docs]

```markdown
# User API

## Endpoints

### Get User Profile

```http
GET /api/users/:id

Authorization: Bearer <token>

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "name": "John Doe",
  "createdAt": "2025-01-15T10:30:00Z"
}

curl -H "Authorization: Bearer abc123" \
  https://api.example.com/api/users/550e8400-e29b-41d4-a716-446655440000

PUT /api/users/:id

{
  "name": "Jane Doe",
  "bio": "Software developer"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "name": "Jane Doe",
  "bio": "Software developer",
  "updatedAt": "2025-01-15T11:00:00Z"
}

User: "Create a changelog for v2.0.0"

[Documentation Writer - Changelog]

```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/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [2.0.0] - 2025-03-04

### Added
- User profile customization with avatar upload
- Real-time notifications via WebSocket
- Dark mode support
- Export data to CSV
- Email verification for new accounts

### Changed
- **BREAKING**: API authentication now requires JWT instead of API keys
- Improved search performance by 3x
- Updated Node.js requirement to v20+
- Redesigned dashboard UI

### Fixed
- Fixed memory leak in WebSocket connections
- Resolved race condition in task creation
- Fixed pagination bug on user list
- Corrected timezone handling for scheduled tasks

### Removed
- **BREAKING**: Removed legacy v1 API endpoints
- Removed deprecated `status` field from tasks

### Security
- Updated all dependencies to patch security vulnerabilities
- Implemented rate limiting on authentication endpoints
- Added Content Security Policy headers

## [1.5.0] - 2025-02-01

### Added
- Task filtering by status and date
- Bulk task operations

### Fixed
- Fixed issue with task deletion

## [1.0.0] - 2025-01-01

### Added
- Initial release
- Basic CRUD operations for tasks
- User authentication

## Quality Checklist

- [ ] Can someone new get started in 5 minutes?
- [ ] Are examples working and tested?
- [ ] Is it up to date with the code?
- [ ] Is the structure scannable?
- [ ] Are edge cases documented?

## Anti-Patterns

| ❌ Don't | ✅ Do |
|----------|-------|
| Write documentation automatically | Wait for explicit request |
| Document everything | Document what's unclear |
| Write once, never update | Keep docs in sync with code |
| Use jargon without explanation | Write for your audience |
| Skip examples | Show working examples |

## Best Practices

<CardGroup cols={2}>
  <Card title="Clarity" icon="lightbulb">
    Short and clear beats long and complete
  </Card>
  <Card title="Examples" icon="code">
    Show working examples, not just descriptions
  </Card>
  <Card title="Maintenance" icon="wrench">
    Update docs when code changes
  </Card>
  <Card title="Audience" icon="users">
    Write for who will read it
  </Card>
</CardGroup>

## Automatic Selection Triggers

Documentation Writer is automatically selected when:
- User explicitly says "write", "create", or "update" + "README", "docs", "documentation"
- User asks for "API docs", "changelog"
- User requests "tutorial" or "guide"

<Warning>
NEVER auto-selected during normal development. Only when explicitly requested.
</Warning>

## Related Agents

<CardGroup cols={2}>
  <Card title="Backend Specialist" icon="server" href="/agents/backend-specialist">
    Documents APIs they build
  </Card>
  <Card title="Frontend Specialist" icon="browser" href="/agents/frontend-specialist">
    Documents components they create
  </Card>
</CardGroup>