loom-technical-writing
Technical Writing
Overview
Style, voice, clarity, and structure for software documentation. This skill owns HOW to write well; for the required structure of each artifact (README, ADR, changelog, API reference, docstrings) see loom-documentation. Always read the code before writing — never document from assumption.
Diátaxis: pick one mode per document
The load-bearing framework. Docs fail mostly by mixing modes — a tutorial that digresses into API tables, a reference padded with narrative. Each document serves ONE of four user needs:
| Mode | User is… | Serves | Voice | Anti-pattern if mixed |
|---|---|---|---|---|
| Tutorial | learning | acquisition | "we will…", hand-held, safe | reference detail derails it |
| How-to | working toward goal | application | "to do X, do Y", imperative | teaching concepts slows it |
| Reference | looking something up | information | neutral, exhaustive, dry | opinions/steps bloat it |
| Explanation | trying to understand | understanding | discursive, "why", trade-offs | step lists flatten the "why" |
Rules: title how-tos by the goal ("Deploy to staging", not "Deployment"). Tutorials must succeed on a clean machine end-to-end. Reference mirrors code structure and stays complete. Explanation (ADRs, design docs) argues the "why". When a page wants to do two jobs, split it and cross-link.