Documentation Skill

# Documentation Skill

## Activation Context
Activates when creating or updating documentation, API docs, user guides, or technical writing.

## When to Invoke documentation-engineer Agent
- Creating user documentation
- Writing API documentation
- Updating README files
- Creating architecture diagrams
- Writing onboarding guides
- Maintaining wikis
- Creating tutorials

## Documentation Types

### Technical Documentation
- **Architecture Docs** (`/docs/architecture/`):
  - System architecture diagrams
  - Component design
  - Data flow diagrams
  - Integration points

- **API Documentation** (`/docs/api/`):
  - Endpoint specifications
  - Request/response examples
  - Authentication guides
  - Error codes and handling
  - Rate limiting

- **ADRs** (`/docs/decisions/`):
  - Architecture Decision Records
  - Context and rationale
  - Consequences
  - Alternatives considered

### User Documentation
- **User Guides** (`/docs/user/`):
  - Feature guides
  - How-to tutorials
  - FAQ
  - Troubleshooting

- **README Files**:
  - Project overview
  - Setup instructions
  - Usage examples
  - Contributing guidelines

### Developer Documentation
- **Onboarding** (`/docs/onboarding/`):
  - Development environment setup
  - Code style guide
  - Git workflow
  - Review process

- **Code Documentation**:
  - Inline comments for complex logic
  - Function/method documentation
  - Type definitions
  - Examples

## Coordination Protocol

### Documentation Update Workflow
1. **Feature Development**: Get requirements from engineer
2. **Draft**: Create initial documentation
3. **Review**: Have relevant engineer review for accuracy
4. **Publish**: Update documentation and notify team
5. **Maintain**: Update as features change

### When Documentation is Required
- **Every new feature** (from product-manager or engineers)
- **Every API change** (from backend-engineer)
- **Every architecture change** (from architect)
- **Every deployment change** (from devsecopsengineer)
- **Every security update** (from security-engineer)

### Handoff Points
- **From product-manager**: Feature specifications to document
- **From architect**: Architecture decisions to record
- **From backend-engineer**: API changes to document
- **From frontend-engineer**: UI features to document in user guide
- **From qa-engineer**: Test plans and procedures
- **From devsecopsengineer**: Deployment and infrastructure docs

## Documentation Standards

### Writing Style
- **Clear and Concise**: Avoid jargon where possible
- **Active Voice**: "Click the button" not "The button should be clicked"
- **Present Tense**: "The API returns" not "The API will return"
- **Consistent Terminology**: Use the same terms throughout
- **Scannable**: Use headings, lists, and formatting

### Structure
```markdown
# Title

## Overview
Brief description of what this is about

## Prerequisites
What you need before starting

## Step-by-Step Instructions
1. First step
2. Second step
3. Third step

## Examples
Code or usage examples

## Common Issues
Troubleshooting guide

## Related Documentation
Links to related docs
```

### Code Examples
- Include working code examples
- Show both request and response
- Include error handling examples
- Use realistic data
- Add comments explaining key parts

### Diagrams
- Use consistent diagram style
- Include legend when needed
- Keep diagrams up to date
- Use tools like Mermaid for version control

## API Documentation Format

```markdown
## Endpoint Name

**Method**: `POST`
**Path**: `/api/v1/users`
**Authentication**: Required (Bearer token)

### Description
Creates a new user account

### Request Headers
| Header | Value | Required |
|--------|-------|----------|
| Authorization | Bearer {token} | Yes |
| Content-Type | application/json | Yes |

### Request Body
\`\`\`json
{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "admin"
}
\`\`\`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User email address |
| name | string | Yes | User full name |
| role | string | No | User role (default: user) |

### Response (201 Created)
\`\`\`json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z"
}
\`\`\`

### Error Responses
- **400 Bad Request**: Invalid input data
  \`\`\`json
  {
    "error": "Validation failed",
    "details": {
      "email": "Invalid email format"
    }
  }
  \`\`\`

- **401 Unauthorized**: Missing or invalid authentication
- **409 Conflict**: User with email already exists

### Example
\`\`\`bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","name":"John Doe","role":"admin"}'
\`\`\`
```

## ADR Template

```markdown
# ADR-XXX: [Decision Title]

**Date**: YYYY-MM-DD
**Status**: [Proposed | Accepted | Deprecated | Superseded]
**Deciders**: [List of people involved]

## Context
What is the issue we're facing? What factors are driving this decision?

## Decision
What is the change we're proposing or have agreed to implement?

## Consequences

### Positive
- What becomes easier or better?
- What risks are reduced?

### Negative
- What becomes harder or worse?
- What new risks are introduced?

### Neutral
- What stays the same?

## Alternatives Considered
1. **Alternative 1**: Description and why it wasn't chosen
2. **Alternative 2**: Description and why it wasn't chosen

## References
- Links to discussions, documentation, or resources
```

## Documentation Maintenance

### Regular Reviews
- **Monthly**: Review and update getting started guides
- **Quarterly**: Review API documentation
- **After major releases**: Update all affected documentation
- **When features deprecated**: Add deprecation notices

### Deprecation Notices
```markdown
> ⚠️ **DEPRECATED**: This endpoint is deprecated and will be removed in v3.0.
> Use `/api/v2/users` instead. See [migration guide](./migration-v2-to-v3.md).
```

### Version Control
- Keep documentation in same repo as code
- Update docs in same PR as code changes
- Version documentation with releases
- Maintain changelog

## Documentation Checklist

### For New Features
- [ ] User guide created/updated
- [ ] API documentation added (if applicable)
- [ ] Code examples provided
- [ ] README updated if needed
- [ ] Migration guide (if breaking changes)
- [ ] Diagrams updated
- [ ] ADR created for significant decisions

### For API Changes
- [ ] All endpoints documented
- [ ] Request/response examples included
- [ ] Error codes documented
- [ ] Authentication requirements clear
- [ ] Rate limiting documented
- [ ] Versioning strategy explained

## Best Practices
- Documentation is never "done"
- Update docs with code changes
- Include examples for everything
- Write for your audience (users vs developers)
- Get feedback from users
- Use screenshots/videos for UI features
- Link related documentation
- Keep it searchable
- Version breaking changes