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.
Know your audience
- Developers — API details, code examples, technical depth.
- End users — tasks and outcomes; minimal jargon.
- Operators/DevOps — deploy, config, monitoring, troubleshooting.
- New contributors — onboarding, architecture overview, contribution workflow.
Prose style
- Active voice. "The function returns X" not "X is returned".
- Imperative for instructions. "Run the command" not "You should run".
- Present tense for current behavior.
- One idea per sentence. Split any sentence with two clauses joined by "and/but/which"; aim 15-25 words. Delete throat-clearing ("It should be noted that…").
- Front-load. Lead each paragraph, section, and sentence with its most important point; put the conclusion first, support after. Readers scan — reward the scan.
- Specific, not hedged. "Returns an empty list" not "returns the result"; "does X" not "might do X". Every "usually/typically/generally" hides an unstated condition — state it.
- Minimalism. Cut words that don't change meaning: "in order to"→"to", "is able to"→"can", "at this point in time"→"now". If a sentence survives deletion, delete it.
- Parallel structure in lists; consistent terminology (one term per concept — never alternate "user/account/profile" for the same thing).
- Define terms on first use; expand acronyms once.
BEFORE: In order to be able to configure the timeout, it is possible for
the user to make use of the --timeout flag if desired.
AFTER: Set the timeout with the --timeout flag.
Docs-as-code
Treat docs like source: in the repo next to the code, changed in the same PR, reviewed, linted, and tested in CI.
- Markdown/MDX under version control; docs PR reviewed like code.
- Lint prose and structure (markdownlint, Vale) in CI; fail the build on broken internal links.
- Test code samples — extract and run them, or use doctests (rustdoc,
pytest --doctest-modules) so examples can't silently rot. - Version docs with the code they describe; update docs in the same commit as the behavior change (stale docs are worse than none).
- Generate reference where possible (typedoc, rustdoc, OpenAPI) so it can't drift.
Error messages
User-facing errors are documentation. Structure: what happened → why → what to do. Be specific; give an actionable next step; never blame the user; keep a neutral tone.
GOOD:
Error: Configuration file not found at './config.json'
The app looks for config.json in the current directory.
Fix: create config.json in your project root, or pass --config /path/to/config.json.
BAD:
Error: null reference exception
Invalid input
Prefer "The file was not found" over "You didn't provide a file".
Release notes vs changelog
A changelog is exhaustive reference (see loom-documentation). Release notes are curated communication — lead with user impact, group by Features / Improvements / Bug Fixes / Breaking Changes, and provide a migration path for every breaking change.
# v2.5.0 — January 2026
## Highlights
One paragraph on the most important change and why users care.
## Breaking Changes
### Changed authentication flow
**Impact:** all API clients must update auth code.
Before: `client.authenticate(token)`
After: `client.authenticate({ token, type: 'bearer' })`
**Migration deadline:** v3.0.
Migration guide
Structure: overview (why migrate) → breaking changes as before/after code pairs → numbered step-by-step → deprecation timeline (when old is removed). Make the happy-path upgrade copy-pasteable.
Anti-patterns
- Mixing Diátaxis modes in one page (most common failure).
- Passive voice and hedging that obscure who does what and what actually happens.
- Wall-of-text with no front-loading; burying the key point in paragraph three.
- Inconsistent terminology for one concept.
- Untested examples; docs updated in a separate PR from the code (they drift).
Verify before done
- Document serves exactly one Diátaxis mode, titled/voiced to match.
- Active voice, present tense, imperative instructions; no hedging.
- Front-loaded: key point first in each section/paragraph/sentence.
- Terminology consistent; acronyms expanded on first use.
- Code samples run; internal links resolve; artifact structure matches
loom-documentation. - Written for the identified audience at the right depth.