---
name: writing-technical-documentation
description: Writes READMEs, architecture docs, and runbooks that lead with purpose, put a working quickstart first, and stay ruthlessly scannable. Use when the user asks to write or improve a README, project documentation, an architecture document, a design doc, a runbook, or internal engineering docs. Do not use for API endpoint reference docs, step-by-step tutorials, or user-facing release notes — separate skills cover those.
---

<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Writing Technical Documentation

## When to use / when NOT to use
- **Use for:** READMEs, architecture/design docs, runbooks, onboarding docs, internal engineering documentation.
- **Do NOT use for:** API endpoint reference (writing-api-documentation), step-by-step tutorials (writing-tutorials), release notes (writing-release-notes), or blog posts (writing-blog-posts).

## House rules

1. **Lead with what it is and who it's for — first two sentences.**
   - ✅ "payment-router routes card transactions to the cheapest eligible processor. It's used by the checkout service; most engineers only need the client library."
   - ❌ "Welcome to the payment-router repository! This document describes the project."

2. **Quickstart before reference.** A copy-paste working example must appear in the first screen of a README.
   - ✅ Install command + minimal working snippet within the first 30 lines.
   - ❌ Three screens of architecture background before the first runnable command.

3. **Document the why, not just the what** (ADR mini-pattern: Context → Decision → Consequences).
   - ✅ "We chose SQS over Kafka because volume is under 100 msg/s and we already pay for AWS. Revisit if we need replay."
   - ❌ "The system uses SQS."

4. **Docs live next to the code and change in the same PR.**
   - ✅ "Updated `docs/runbook.md` in the PR that changed the alert threshold."
   - ❌ A wiki page last edited two majors ago.

5. **Ruthless scannability.** A heading roughly every 10 lines; tables for enumerable facts; every code block tested before committing.
   - ✅ A "Configuration" table with name/default/effect columns.
   - ❌ Configuration options described across four paragraphs of prose.

6. **No marketing adjectives.** Claims must be verifiable.
   - ✅ "Handles 2,000 requests/s on one c7g.large."
   - ❌ "Blazingly fast, robust, and seamless."

7. **Date-stamp anything that rots.** Benchmarks, dependency lists, screenshots, on-call contacts get an "as of YYYY-MM" marker.
   - ✅ "Benchmarks (as of 2026-08): …"
   - ❌ Undated numbers that outlive their truth.

## Workflow

1. Identify the doc type (README / architecture doc / runbook) and the primary reader; write both at the top as the first two sentences.
2. Draft the skeleton: purpose → quickstart → how it works → reference → operations. For runbooks: symptom → diagnosis → fix → escalation.
3. Write the quickstart first and actually run every command in it.
4. Fill remaining sections; convert any enumerable prose into tables.
5. Self-review against the seven house rules; delete every unverifiable adjective; add date stamps; fix violations before delivering.

## Edge cases
- **Existing doc to improve** → preserve its structure where sound; apply rules 1–2 first (purpose and quickstart), then scannability. List what you changed.
- **No runnable quickstart possible** (pure library of internals, docs-only repo) → substitute a "minimal usage" code snippet or a "start here" reading path.
- **Audience is mixed** (users + contributors) → split: README for users, CONTRIBUTING/ARCHITECTURE for contributors. Never interleave.

## References
Extended before/after examples: see [references/examples.md](references/examples.md).