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

# 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

## 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

# 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

> ⚠️ **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