Technical Writing — Template Index
| Field | Value |
|---|---|
| Type | Skill Resource |
| Source | ~/.copilot/skills/technical-writing/references/templates.md |
| Description | Not specified |
Source Content
Technical Writing — Template Index
One file per template lives in templates/. Copy the skeleton for your mode, then fill it. Headings inside each skeleton are noun-phrase promises — keep them specific, never “Overview”. Decision records use the adr skill’s template instead of anything here.
Picking a template
| Template | The reader’s job | Reach for it when |
|---|---|---|
| Tutorial | Learning by doing | The reader is new and should finish with something built |
| How-to guide | Achieving a goal | The reader knows the basics and wants the recipe |
| Reference | Looking something up | Exact parameters, behavior, and examples |
| Explanation | Understanding why | Design rationale, mental models, tradeoffs |
| README | Getting oriented | The front door of a repo |
| Migration guide | Moving safely | Old way → new way without breakage |
| Blog post | Reading for the payoff | Narrative with a technical payoff |
| Troubleshooting | Getting unstuck | Symptom-first help for a stuck reader |
| FAQ | Quick answers | Real questions users actually asked |
| Release notes | Knowing what changed | Shipping a version users must react to |
| Runbook | Restoring service | Operational steps for a paged engineer |
| Status update | Deciding fast | Weekly exec/stakeholder state: BLUF, wins, risks + asks |
| User survey | Being heard | Collecting stories, not just ratings |
If two templates seem to fit, it is two documents. Split them and cross-link.
What every template already includes
- An opening two-person story slot — one persona hits the problem, the other takes the better path, cast and rotated from personas.md. Every doc type opens with one: runbooks and troubleshooting get a 2–3 sentence incident scene; reference, release notes, and status updates get one line at most.
- A one-line casting hint in each template’s rules — which personas fit that doc type.
- A slot for a Mermaid diagram wherever flow, structure, or decisions appear — always per
mermaid.md. - The key-value rule: config pairs, flags, and metadata one per line, never chained in prose.
- Per-template rules at the bottom of each file — read them before filling the skeleton.
After filling a template, gate the result — one command runs every registered lint:
python3 ~/.copilot/skills/technical-writing/scripts/lint.py docs/your-doc.md