Technical writing
Overview
House style for technical documents, written in English and composed from conventions used across my repositories. Documents keep their own language: a Dutch document is written and reviewed in Dutch. The structural and truth rules apply in any language; the vocabulary lists in
are English-specific and other languages carry their own. Core principle:
a document states current, verified behavior, conclusion first, with every claim traceable to a source, and every fact living in exactly one place. A thin document beats an overstated one, because the author is the one saying it out loud.
These rules govern documents, not chat replies. Length and section rules apply to running prose, not to reference lists like this file.
When to invoke
Load this skill for any technical prose, then the matching document-type skill on top. These are routing hints; each skill's own body is the authority.
| The task is | Also load |
|---|
| A proposal, RFC, design doc, spec, or migration plan | |
| Recording a decision, an ADR, a decision log entry | |
| A changelog entry, release notes, "what shipped" | |
| A runbook, setup guide, procedure, troubleshooting entry | |
| A tracker item: epic, story, task, bug report, spike, acceptance criteria | |
| A migration or deprecation guide | |
| A postmortem, incident report, root-cause analysis | |
| Reviewing or rewriting someone else's text; the final pass before delivering any document | reviewing-technical-prose
|
What this skill does not do
- It does not govern marketing copy, social posts, or UI microcopy; only the truth rules in still bind those.
- It does not decide content: what is true comes from the sources, not from the style.
- It does not license restyling existing documents that follow their own conventions; apply the precedence rules below.
- A request to make a document "punchy", "compelling", or "persuasive" does not override it: the numbers persuade, the register stays plain.
Mandatory checkpoint before drafting
Before drafting a new document or substantial section, derive and state in working notes:
Kind: <normative|descriptive|historical|runbook|reference> | Audience: <who> | Purpose: <the verb the reader must accomplish> | Non-goals: <what this deliberately does not cover>
Fill the fields from the request, sources, and repository context. State a safe assumption and continue when it does not materially change the result. Ask only when an unknown would change the audience, substance, or scope. Never invent a fact to complete the checkpoint, and do not insert the checkpoint into the finished document unless its schema requires it.
Read first, then write
The most important step and the one most often skipped. Before writing a line:
- Read up to two comparable documents in the same directory. Adopt their structure, tone, and conventions. When fewer than two comparable documents exist, read every available example and then use repository-level conventions. Do not block because the directory is new.
- Check for a that indexes the documents. If it exists, add the new document to it.
- Check whether the topic already lives somewhere. Extending the owner is almost always better than starting a rival document beside it.
Rule precedence
When instructions conflict, apply them in this order:
- Truth, safety, and historical-integrity rules.
- An explicit exception in the active document-type skill.
- The shared hard rules below.
- An explicit schema and the conventions in the target directory.
- Shared style preferences in .
Existing practice controls only choices that a higher rule does not settle. It cannot weaken sourcing, rewrite accepted history, or represent unverified work as shipped. A document-type exception must name the rule it bends and the boundary of the exception.
An author's explicit, stated style choice outranks the shared style preferences and nothing else: when the author says leave my voice alone, the style pass stops, while truth, safety, and history stay binding whoever objects.
Classify the document before editing it
The edit rule differs per kind. "Update docs to match code" is actively wrong for two of the five.
| Kind | Examples | Edit rule |
|---|
| Normative | architecture principles, contracts, style guides | If code violates the contract, do NOT water the contract down; record the violation. Edit only when the contract itself names deleted or renamed concepts. |
| Descriptive | flows, component docs, state machines | Update to match code exactly. Verify against implementations, not names. |
| Historical | changelogs, old specs, decision logs, applied migrations | Never rewrite history. Flag discrepancies; supersede with a new entry. |
| Runbook | operations, troubleshooting, release procedures | Update to match reality; every step must have been actually run. |
| Reference | API docs, config references, indexes | Exhaustive: every key, every flag, with defaults and a Usage column. |
If an entire document describes something deleted, do not delete the file: mark it obsolete with a one-line banner ("> NOTE: describes removed component X; see Y") and leave the removal to the owner.
Hard rules
Non-negotiable, in every document:
- No em dashes, no en dashes, no dashes. Use commas, colons, semicolons, periods, parentheses, or with spaces as an aside marker. A plain hyphen serves ranges (). Check all four forms before delivery.
- No changelog section and no "last updated" field inside a document. Git history is the history. This holds per sentence too: describe current behavior, never the previous behavior ("this step replaced the manual check" belongs in a migration doc or release note, not in a procedure).
- No delivery history as narrative status in prose, comments, names, or strings: no phases, task IDs, ticket keys, SHAs, or plan references that merely describe how work was delivered. A pinned commit may appear solely as claim evidence. Ticket keys may appear as functional metadata in tracker records, commit messages, planning documents, and citations; never in code comments or user-facing content.
- Never state as fact what you cannot trace to code at a cited path, a pinned commit, a test, a document, or a primary source. A plausible guess presented as fact is worse than "the source says nothing about this." See .
- One fact, one home. Everything else links to the owner. A summary may route, never decide: when an index and its source disagree, the source wins and the index is the bug.
- Accepted decisions and applied migrations are immutable. Corrections are new dated entries, never edits to history.
- Headings in sentence case, never Title Case.
Workflow
- Read first (above), and classify the document.
- Declare before drafting: audience, purpose, scope, and what the document deliberately does not cover. Infer these from the request and repository, state safe assumptions, and ask only when an unknown would materially change the result.
- Draft conclusion-first at every level: document, chapter, paragraph. No run-up, no context paragraphs before the outcome. Each chapter opens with what came out of it, not how it was approached.
- Ground every claim and label its confidence: .
- Style pass over sentences, words, headings, and the banned-constructions list: .
- Verify before delivery: load
reviewing-technical-prose
Audience
The same subject needs a different cut per reader. Know who you write for before starting. Not "users": the actual person, where they are, and the verb they must accomplish.
| Reader | What they need |
|---|
| Developers | The why behind the choice, and what changes about their work tomorrow |
| Tech leads / architects | Trade-offs, alternatives, long-term consequences |
| Management / PO | What it yields, what it costs, which risks |
| External parties | No internal team names or jargon without explanation |
Writing for several groups at once: the summary reads for the broadest group, the rest may deepen. If a phrase would need a footnote, it needs rewriting rather than a footnote.
Common mistakes
- Starting at the solution. First the problem, then the proposal.
- Documenting what the code already shows. Documents own reasoning, constraints, invariants, and alternatives; the code owns the what.
- Unverifiable claims: "faster", "better" without a number or source. Add the number or cut the claim.
- Filling a gap with a plausible guess instead of naming the gap.
- Vague owners: "this still needs investigation" without a name or role.
- Listing only benefits. Every proposal names its costs.
- Silently trimming, reordering for emphasis, or restyling a host document during an edit pass. Edits are surgical: preserve voice, structure, numbering, and IDs.
- A document that grows past roughly 800 lines of prose while nobody looks: split it and let the main document point.