spb/ultra-sharp-agent-skills Public

1---2name: writing-technical-documentation3description: 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.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Writing Technical Documentation1213## When to use / when NOT to use14- **Use for:** READMEs, architecture/design docs, runbooks, onboarding docs, internal engineering documentation.15- **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).1617## House rules18191. **Lead with what it is and who it's for — first two sentences.**20   - ✅ "payment-router routes card transactions to the cheapest eligible processor. It's used by the checkout service; most engineers only need the client library."21   - ❌ "Welcome to the payment-router repository! This document describes the project."22232. **Quickstart before reference.** A copy-paste working example must appear in the first screen of a README.24   - ✅ Install command + minimal working snippet within the first 30 lines.25   - ❌ Three screens of architecture background before the first runnable command.26273. **Document the why, not just the what** (ADR mini-pattern: Context → Decision → Consequences).28   - ✅ "We chose SQS over Kafka because volume is under 100 msg/s and we already pay for AWS. Revisit if we need replay."29   - ❌ "The system uses SQS."30314. **Docs live next to the code and change in the same PR.**32   - ✅ "Updated `docs/runbook.md` in the PR that changed the alert threshold."33   - ❌ A wiki page last edited two majors ago.34355. **Ruthless scannability.** A heading roughly every 10 lines; tables for enumerable facts; every code block tested before committing.36   - ✅ A "Configuration" table with name/default/effect columns.37   - ❌ Configuration options described across four paragraphs of prose.38396. **No marketing adjectives.** Claims must be verifiable.40   - ✅ "Handles 2,000 requests/s on one c7g.large."41   - ❌ "Blazingly fast, robust, and seamless."42437. **Date-stamp anything that rots.** Benchmarks, dependency lists, screenshots, on-call contacts get an "as of YYYY-MM" marker.44   - ✅ "Benchmarks (as of 2026-08): …"45   - ❌ Undated numbers that outlive their truth.4647## Workflow48491. Identify the doc type (README / architecture doc / runbook) and the primary reader; write both at the top as the first two sentences.502. Draft the skeleton: purpose → quickstart → how it works → reference → operations. For runbooks: symptom → diagnosis → fix → escalation.513. Write the quickstart first and actually run every command in it.524. Fill remaining sections; convert any enumerable prose into tables.535. Self-review against the seven house rules; delete every unverifiable adjective; add date stamps; fix violations before delivering.5455## Edge cases56- **Existing doc to improve** → preserve its structure where sound; apply rules 1–2 first (purpose and quickstart), then scannability. List what you changed.57- **No runnable quickstart possible** (pure library of internals, docs-only repo) → substitute a "minimal usage" code snippet or a "start here" reading path.58- **Audience is mixed** (users + contributors) → split: README for users, CONTRIBUTING/ARCHITECTURE for contributors. Never interleave.5960## References61Extended before/after examples: see [references/examples.md](references/examples.md).62