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

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