technical-writing

When this skill is activated, always start your first response with the 🧢 emoji.

Technical Writing

Technical writing for software teams is the practice of producing clear, accurate, and maintainable documentation that helps developers understand systems, use APIs, follow procedures, and make informed architectural decisions. Good technical docs reduce onboarding time, prevent production incidents, and eliminate tribal knowledge. This skill covers the five core document types every engineering organization needs: API docs, tutorials, architecture docs, ADRs, and runbooks.

When to use this skill

Trigger this skill when the user:

• Needs to write or improve API documentation (REST, GraphQL, gRPC)
• Wants to create a step-by-step tutorial or getting-started guide
• Asks to write an Architecture Decision Record (ADR)
• Needs to produce a runbook for an operational procedure
• Wants to document system architecture or design
• Asks to review existing documentation for clarity or completeness
• Needs a README, onboarding guide, or contributor guide
• Wants to establish documentation standards for a team

Do NOT trigger this skill for:

• Marketing copy, blog posts, or sales content (use content-marketing skill)
• Code comments and inline documentation only (use clean-code skill)

Key principles

1. Write for the reader, not yourself - Identify who will read this doc and what

they need to accomplish. A new hire reading a tutorial has different needs than an on-call engineer reading a runbook at 3 AM. Adjust depth, tone, and structure accordingly.

1. Optimize for scanning - Engineers rarely read docs linearly. Use headings,

bullet lists, tables, and code blocks so readers can find what they need in under 30 seconds. Front-load the most important information in every section.

1. Show, then tell - Lead with a concrete example (code snippet, command, or

screenshot), then explain what it does. Abstract explanations without examples force the reader to build a mental model from scratch.

1. Keep docs close to code - Documentation that lives in the repo (Markdown,

OpenAPI specs, doc comments) stays current. Documentation in wikis or external tools drifts and dies. Treat docs as code: review them in PRs, lint them in CI.

1. One document, one purpose - A tutorial teaches. A reference answers. A runbook

instructs. Never mix purposes in a single document - a tutorial that detours into reference tables loses the reader.

Core concepts

Technical documentation falls into five categories, each with a distinct audience, structure, and maintenance cadence:

API Documentation is the reference layer. It describes every endpoint, parameter, response shape, and error code. The audience is developers integrating with your system. API docs are high-frequency reads and must be exhaustively accurate. See references/api-docs.md.

Tutorials are the learning layer. They walk a reader from zero to a working outcome through ordered steps. The audience is new users. Tutorials must be reproducible - every step should produce a predictable result. See references/tutorials.md.

Architecture Documentation is the context layer. It explains how a system is structured and why, using diagrams and prose. The audience is engineers joining the team or making cross-cutting changes. See references/architecture-docs.md.

Architecture Decision Records (ADRs) are the history layer. Each ADR captures a single decision - the context, options considered, and the chosen approach with rationale. They are immutable once accepted. See references/adrs.md.

Runbooks are the action layer. They provide step-by-step instructions for operational tasks - deployments, incident response, data migrations. The audience is on-call engineers under pressure. See references/runbooks.md.

Common tasks

Write API endpoint documentation

For each endpoint, include these fields in order:

### POST /api/v1/users

Create a new user account.

**Authentication:** Bearer token (required)

**Request body:**

| Field    | Type   | Required | Description              |
|----------|--------|----------|--------------------------|
| email    | string | yes      | Valid email address       |
| name     | string | yes      | Display name (2-100 chars)|
| role     | string | no       | One of: admin, member     |

**Response (201 Created):**

{ "id": "usr_abc123", "email": "dev@example.com", "name": "Ada Lovelace", "role": "member", "created_at": "2025-01-15T10:30:00Z" }

**Errors:**

| Status | Code             | Description                  |
|--------|------------------|------------------------------|
| 400    | invalid_email    | Email format is invalid      |
| 409    | email_exists     | Account with email exists    |
| 401    | unauthorized     | Missing or expired token     |

Always include a realistic response example with plausible data, not placeholder

values like "string" or "0".

Write a step-by-step tutorial

Use this structure for every tutorial:

1. Title - "How to [accomplish specific goal]"
2. Prerequisites - What the reader needs before starting (tools, accounts, prior knowledge)
3. Steps - Numbered, each with one action and its expected outcome
4. Verify - How to confirm the tutorial worked
5. Next steps - Where to go from here

Each step should follow this pattern:

## Step 3: Configure the database connection

Add your database URL to the environment file:

echo 'DATABASE_URL=postgres://localhost:5432/myapp' >> .env

You should see the variable when you run `cat .env`.

Never assume the reader can infer a step. If you deleted a step and the tutorial

would still work, the step is load-bearing for understanding, not execution - keep

it but mark it as context.

Write an Architecture Decision Record (ADR)

Use the Michael Nygard format:

# ADR-007: Use PostgreSQL for the primary datastore

## Status

Accepted (2025-03-10)

## Context

The application needs a relational datastore that supports ACID transactions,
JSON columns for semi-structured data, and full-text search. The team has
production experience with PostgreSQL and MySQL.

## Decision

Use PostgreSQL 16 as the primary datastore.

## Consequences

- **Positive:** Native JSONB support eliminates the need for a separate
  document store. Full-text search via tsvector avoids an Elasticsearch
  dependency.
- **Negative:** Requires operational expertise for vacuum tuning and
  connection pooling at scale. Team must learn PostgreSQL-specific features
  (CTEs, window functions) that differ from MySQL.
- **Neutral:** Migration tooling (pgloader) is available if we need to move
  data from the existing MySQL instance.

ADRs are immutable. If a decision is reversed, write a new ADR that supersedes

the original. Never edit an accepted ADR.

Write a runbook

Structure every runbook for someone who is stressed, tired, and unfamiliar with the system:

# Runbook: Database failover to read replica

**Severity:** SEV-1 (data serving impacted)
**Owner:** Platform team
**Last tested:** 2025-02-20
**Estimated time:** 10-15 minutes

## Symptoms

- Application returns 500 errors on all database-backed endpoints
- Database primary shows `connection refused` or replication lag > 60s

## Prerequisites

- Access to AWS console (production account)
- `kubectl` configured for the production cluster
- Pager notification sent to #incidents channel

## Steps

1. Verify the primary is actually down:
   ```bash
   pg_isready -h primary.db.internal -p 5432
   ```
   Expected: "no response" or connection refused.

2. Promote the read replica:
   ```bash
   aws rds promote-read-replica --db-instance-identifier myapp-replica-1
   ```
   Wait for status to change to "available" (3-5 minutes).

3. Update the application config:
   ```bash