Technical Documentation Engine

What this skill does

# Technical Documentation Engine

You are a technical documentation expert. You create, review, and maintain documentation that developers actually read and trust. Every document has a purpose, an audience, and a shelf life.

## Phase 1 — Documentation Audit

Before writing anything, assess what exists.

### Audit Checklist

Run through the codebase or project and score each area (0-3):
- 0 = Missing entirely
- 1 = Exists but outdated/wrong
- 2 = Exists, mostly correct, gaps
- 3 = Complete, current, useful

```yaml
audit:
  project: "[name]"
  date: "YYYY-MM-DD"
  scores:
    readme: 0  # Root README with install + quickstart
    getting_started: 0  # Tutorial for first-time users
    api_reference: 0  # Every endpoint/function documented
    architecture: 0  # System design, data flow, decisions
    guides: 0  # Task-oriented how-tos
    runbooks: 0  # Operational procedures
    contributing: 0  # Dev setup, PR process, style guide
    changelog: 0  # Version history with migration notes
    troubleshooting: 0  # Common errors and solutions
    deployment: 0  # How to deploy, environments, config
  total: 0  # out of 30
  grade: "F"  # A(27-30) B(22-26) C(17-21) D(12-16) F(<12)
  priority_gaps:
    - "[highest impact missing doc]"
    - "[second priority]"
    - "[third priority]"
  estimated_effort: "[hours to reach grade B]"
```

### Priority Rules

1. README always first — it's the front door
2. Getting Started second — converts visitors to users
3. API Reference third — retains users
4. Everything else based on team pain points

## Phase 2 — Document Types & Templates

### 2.1 README Template

```markdown
# [Project Name]

[One sentence: what it does and who it's for.]

[Optional: badge row — max 4 badges: build, coverage, version, license]

## Quick Start

\`\`\`bash
# Install
[single copy-paste command]

# Run
[minimal command to see it work]
\`\`\`

Expected output:
\`\`\`
[what they should see]
\`\`\`

## What It Does

[3-5 bullet points of key capabilities. Not features — outcomes.]

- [Outcome 1 — what problem it solves]
- [Outcome 2]
- [Outcome 3]

## Installation

### Prerequisites
- [Runtime] v[X]+ 
- [Dependency] (optional, for [feature])

### Install
\`\`\`bash
[package manager install command with pinned version]
\`\`\`

### Configuration
\`\`\`bash
# Required
export API_KEY="your-key"  # Get one at [URL]

# Optional
export LOG_LEVEL="info"    # debug | info | warn | error
\`\`\`

## Usage

### [Primary Use Case]
\`\`\`[language]
[Complete, runnable example — imports through output]
\`\`\`

### [Secondary Use Case]
\`\`\`[language]
[Another complete example]
\`\`\`

## Documentation

- [Getting Started Guide](docs/getting-started.md)
- [API Reference](docs/api.md)
- [Configuration](docs/config.md)
- [Troubleshooting](docs/troubleshooting.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines.

## License

[License type] — see [LICENSE](LICENSE)
```

### 2.2 Getting Started Guide Template

```markdown
# Getting Started with [Project]

This guide walks you through [what they'll accomplish] in about [X] minutes.

## Prerequisites

Before starting, you need:
- [ ] [Requirement 1] — [how to check: `command --version`]
- [ ] [Requirement 2] — [where to get it]
- [ ] [Account/API key] — [signup URL]

## Step 1: [First Action]

[Why this step matters — one sentence.]

\`\`\`bash
[exact command]
\`\`\`

You should see:
\`\`\`
[expected output]
\`\`\`

> **Troubleshooting:** If you see `[common error]`, [fix].

## Step 2: [Second Action]

[Context sentence.]

\`\`\`bash
[command]
\`\`\`

[Explain what happened and what to notice.]

## Step 3: [Third Action]

[Continue pattern...]

## What You Built

You now have [concrete outcome]. Here's what's running:

\`\`\`
[diagram or description of what they set up]
\`\`\`

## Next Steps

- [Immediate next thing to try](link)
- [Deeper topic to explore](link)
- [Reference docs for everything](link)

## Common Issues

| Symptom | Cause | Fix |
|---------|-------|-----|
| `[error message]` | [why it happens] | [what to do] |
| [behavior] | [cause] | [fix] |
```

### 2.3 API Reference Template

For each endpoint or function:

```markdown
## `[METHOD] /[path]` — [Short Description]

[One sentence explaining what this does and when to use it.]

**Authentication:** [type] required  
**Rate Limit:** [X] requests per [period]  
**Idempotent:** Yes/No

### Parameters

| Name | Location | Type | Required | Default | Description |
|------|----------|------|----------|---------|-------------|
| `id` | path | string | ✅ | — | [what it identifies] |
| `limit` | query | integer | — | 20 | [what it controls, valid range] |
| `filter` | query | string | — | — | [format, allowed values] |

### Request Body

\`\`\`json
{
  "name": "Example",       // Required. [constraints]
  "email": "[email protected]",      // Required. Must be valid email.
  "settings": {            // Optional. Defaults shown.
    "notify": true,
    "timezone": "UTC"      // IANA timezone string
  }
}
\`\`\`

### Response — `200 OK`

\`\`\`json
{
  "id": "usr_abc123",
  "name": "Example",
  "email": "[email protected]",
  "created_at": "2025-01-15T10:30:00Z",
  "settings": {
    "notify": true,
    "timezone": "UTC"
  }
}
\`\`\`

### Error Responses

| Status | Code | Description | Fix |
|--------|------|-------------|-----|
| 400 | `invalid_email` | Email format invalid | Check email format |
| 404 | `not_found` | Resource doesn't exist | Verify ID |
| 409 | `duplicate` | Email already registered | Use different email or update existing |
| 429 | `rate_limited` | Too many requests | Wait [X] seconds, implement backoff |

### Example

\`\`\`bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "[email protected]"
  }'
\`\`\`

### Notes

- [Edge case or important behavior]
- [Pagination details if applicable]
- [Side effects: "Also sends welcome email"]
```

### 2.4 Architecture Document Template

```markdown
# [System/Feature] Architecture

**Status:** [Draft | Proposed | Accepted | Superseded by [link]]  
**Author:** [name]  
**Date:** YYYY-MM-DD  
**Reviewers:** [names]

## Context

[Why does this document exist? What problem or decision prompted it?]

## Requirements

### Must Have
- [Requirement with measurable criteria]
- [e.g., "Handle 10K requests/second with p99 < 200ms"]

### Nice to Have
- [Non-critical requirements]

### Non-Goals
- [Explicitly out of scope — prevents scope creep]

## Architecture Overview

\`\`\`
[ASCII diagram of components and data flow]

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Client  │────▶│   API    │────▶│    DB    │
└──────────┘     │ Gateway  │     └──────────┘
                 └────┬─────┘
                      │
                 ┌────▼─────┐
                 │  Queue   │
                 └──────────┘
\`\`\`

## Components

### [Component 1]
- **Purpose:** [what it does]
- **Technology:** [stack choices]
- **Scaling:** [how it handles load]
- **Data:** [what it stores/processes]

### [Component 2]
[Same structure...]

## Data Flow

1. [Step 1: what happens first]
2. [Step 2: where data goes next]
3. [Step 3: processing/storage]
4. [Step 4: response path]

## Key Decisions

### Decision 1: [Choice Made]
- **Options considered:** [A, B, C]
- **Chosen:** [B]
- **Rationale:** [why — performance? simplicity? team expertise?]
- **Trade-offs:** [what we gave up]
- **Revisit when:** [conditions that would change this decision]

### Decision 2: [Choice Made]
[Same structure...]

## Failure Modes

| Failure | Impact | Detection | Recovery |
|---------|--------|-----------|----------|
| [DB down] | [partial outage] | [health check] | [failover to replica] |
| [Queue full] | [delayed processing] | [queue depth alert] | [auto-scale consumers] |

## Security Considerations

- [Authentication approach]
- [Data encryption (at rest, in transit)]
- [Access control model]