Technical Writing — Style Guide

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/style-guide.md
Description	Not specified

Source Content

Technical Writing — Style Guide

Document-level craft: audience, voice, structure, readability, and the cut. Mechanical Markdown rules (tables, heading levels, code fences) live in markdown.md — this guide does not repeat them.

Contents

• Audience adaptation
• Readability: the 8th-grade target
• Formatting that carries meaning
• Two-person stories
• Diagrams before paragraphs
• Voice and tone by document type
• Writing principles
• Voice and tone rules
• Voice and register
• Common pitfalls
• Quality checklist

Audience adaptation

Audience	What they want	Tone	Depth signal
Junior developers	Context, definitions, the “why”	Encouraging, patient	Define terms on first use; explain motivations
Senior engineers	Implementation patterns, tradeoffs	Direct, peer-to-peer	Skip basics; show decisions and alternatives
Technical leaders	Strategic implications, architectural impact	Concise, outcome-framed	Lead with consequences; defer mechanics
Non-technical stakeholders	Business value, outcomes	Plain, analogy-driven	Replace jargon; visualize impact

Whatever the audience, assume they landed in the middle of the document from a search result — Mark Baker’s “every page is page one.” Every section must orient the reader in its first line and link out to what it depends on.

Readability: the 8th-grade target

Aim for an 8th-grade reading level in every document. Smart readers are busy readers; nobody ever complained a doc was too easy to read. Some technical words are unavoidably long — the scoring script down-weights repeated domain terms so you are never punished for saying “Kubernetes” correctly.

python3 ~/.copilot/skills/technical-writing/scripts/readability.py docs/guide.md

The script gates on the adjusted Flesch-Kincaid grade (target ≤ 8.9) and flags any paragraph over 4 sentences. When it fails, split the longest sentences it lists, swap Latinate words for short ones (use, not utilize), and cut clauses.

Paragraphs never exceed 4 sentences

This is a hard house rule, stricter than the general limits in markdown.md. If a paragraph needs a fifth sentence, it is two paragraphs — or a list.

Formatting that carries meaning

Formatting is not decoration; it is how a busy reader navigates. Bullets, headings, and line breaks do the work that transition sentences do in essays.

Key-value pairs go on their own line

Anything shaped like name: value never sits inline in a sentence, and never chains. Inline chains like “set mode: fast. retries: 3. debug: off.” are unreadable. Break them out:

<!-- Wrong -->
Set mode: fast, retries: 3, and debug: off before running.

<!-- Correct -->
Set these values before running:

- `mode: fast`
- `retries: 3`
- `debug: off`

The same rule covers config flags, environment variables, HTTP headers, and CLI options. One pair per line, in a list or a code block — the reader scans them vertically.

Bullets versus prose

Use bullets when the items are parallel and order-free; use numbered steps when order matters; use prose when the ideas connect causally. A wall of prose hiding three options is a list in disguise. A bullet list where each item is a full paragraph is prose in disguise.

Two-person stories

When explaining a concept, a tradeoff, or a pitfall, always try to carry it with a short two-person story. Readers take themselves out of the frame and watch someone else — that distance is what makes the lesson land.

The story goes first. Put it at the top of the document or section it carries, before the claim it exists to teach. A story up front paints the picture before anything else is said, so the explanation that follows lands on a scene the reader can already see. A story appended after the explanation is an illustration; a story in front of it is a frame.

The shape is fixed and fast:

1. Jack hits the problem. “Jack cached the API response at the edge and cut latency — then customers started seeing each other’s carts.”
2. Jill takes the better path. “Jill keyed the cache on the session token. Same speedup, no leak.”

Two people, four sentences, done — and each gets their own line. Jack’s sentence ends a paragraph; Jill starts the next one. Never run both into a single paragraph — the break is what signals the story changed hands.

Jack carries the problem and its consequence; Jill carries the solution and its outcome. This beats a long abstract explanation because the reader can replay the story, and it costs less space than the paragraph it replaces. Real stories must be true; hypotheticals must read as hypothetical (“say a team…”) — never invent metrics or company names dressed up as fact.

The useful ending

Every opening story gets a closing one. The useful ending is the document’s conclusion — a short sign-off after all the content, not folded under the opening scene. It waits until the reader has read the whole thing, then returns to Jack and Jill and gives the lesson each of them learned.

Two or three sentences, no new plot — this is a resolution, not a second story. Full documents close with a ## The useful ending heading at the very end. Runbooks and troubleshooting compress it to one line instead of a heading, to match their urgency. Code comments and commit messages stay exempt, same as the opening.

Continuing the example above, the useful ending might read: “Jill’s session key is the default now, and Jack’s leak is the line in the runbook that keeps the next one from happening.” One line, both of them, one outcome.

The cast

The story is always Jack and Jill — Jack takes the path with friction, Jill takes the path that works, and the reader infers which is better. Their roles and the casting rules live in personas.md. This guide keeps the story craft; that file owns the cast.

Diagrams before paragraphs

If a sentence describes structure, flow, sequence, or a decision, a diagram will beat it. Reach for a Mermaid diagram whenever you catch yourself writing “first X happens, then Y, unless Z”. Always follow the diagram rules in mermaid.md before emitting the code block — no exceptions — and put an italic “what to notice” line under every diagram.

Good diagram candidates:

• Request or data flow between services — flowchart or sequence diagram.
• Decision logic (“which template do I use?”) — flowchart with labeled branches.
• Lifecycles and state (“draft → review → published”) — state diagram.
• Timelines and rollout phases — Gantt or timeline.

Voice and tone by document type

Technical blog

Conversational yet authoritative; use “I” / “we” to create connection; lead with a hook.

Reference

Clear, direct, objective; consistent terminology; no narrative voice.

Tutorial

Encouraging, practical, step-by-step; verify after each step.

ADR and architecture

Precise, systematic, decision-focused; record context and tradeoffs. The adr skill owns the record format.

User guide and how-to

Task-oriented; lead with the user’s goal; show outcomes.

Survey and user research

Curious, neutral, specific. Question design lives in question-craft.md — one question per question, concrete over abstract, never leading.

Writing principles

Clarity first. Use simple words for complex ideas, define technical terms on first use, and keep one main idea per paragraph. When the concept is hard, shorten the sentences.

Structure and flow. Start with the why before the how, disclose progressively from simple to complex, and end sections with the takeaway. Signpost transitions.

Task focus. Write for what the reader needs to do, not what the product is. Every section should leave the reader more capable — Kathy Sierra’s “make the user awesome” and Don Norman’s user-centered lens both point here.

Engagement. Open with a hook that establishes relevance, prefer concrete examples over abstractions, and include honest lessons learned.

Use stories to make examples stick. A rule tells the reader what to do; a story shows what happens when they don’t — and the story is what they remember. Lead with it: story first, then the claim it painted, then the lesson (see Two-person stories). Mistakes teach best — borrowed pain is cheap tuition — so keep it a vignette and reserve stories for the points that must stick.

Make every paragraph quotable. Leave at least one line per paragraph that a reader would highlight or build a post around. Land each paragraph on its sharpest sentence and cut the throat-clearing in front of the good line. The plainest sentence is usually the most quotable, so sharpen the point rather than inflate the words — one highlight per paragraph, not a firework in every clause.

Technical accuracy. Every code example runs on the stated stack and versions are pinned. Cross-reference official docs rather than restating them, and note performance implications where relevant.

Voice and tone rules

• Active voice — the function processes data, not data is processed by the function.
• Direct address — use “you” when instructing.
• Inclusive language — “we discovered” for shared work; reserve “I” for personal narrative.
• Confident but humble — “this approach works well”, not “this is the best approach”.

Voice and register

Write in a confident, grounded voice — the doc earns trust by stating the claim, then showing it, not by hedging in front of it. Writer models to channel per doc type live in voice-and-writers.md.

• No throat-clearing. Don’t apologize before the argument or wind up to the good line. Name the objection and move past it in one move.
• Specific over abstract. Drop the reader into a named scene where the claim is visible, and end it on the concrete consequence line — that line is what persuades. Mark composites as composite; never invent metrics or company names as fact.
• Attach each prescription to the failure it prevents. “Run the filter, so we never start an engagement that dies at procurement.” Action plus averted failure is what makes a rule feel earned.
• Terms of art are verbatim. Pick one form of each key term and reuse it exactly — no drifting between “institutional layer” / “institutional path” / “Institutional”.
• Named models and patterns are evidenced, not just labeled. If the doc claims “continuous delivery,” “GitOps,” “blue-green,” or any other named process/architecture pattern, state the mechanism that earns the label — what’s automatic, what’s gated, and by whom — in the same breath as the claim. A label without its mechanism is a buzzword; a reader can’t tell “continuous delivery” from “continuous integration” unless the text (or the diagram) says which steps are unattended and which require a person.

Common pitfalls

Content. Leading with implementation before the problem, assuming too much prior knowledge, missing the “so what?”, and overwhelming with options instead of recommending a default.

Technical. Untested code, outdated version references, platform-specific assumptions stated as universal, and security anti-patterns in example code.

Writing. Passive-voice overuse, jargon without definitions, walls of text without visual breaks, and inconsistent terminology between sections.

Sounding machine-written. Addressing the person who asked for the document instead of the person reading it, and saying “human” where a role belongs — both covered in natural-voice.md.

Quality checklist

• Clarity — a junior developer can follow the main points.
• Readability — scripts/readability.py passes: adjusted grade ≤ 8.9, no paragraph over 4 sentences.
• Accuracy — every technical detail and example actually works.
• Completeness — the promised topics are covered.
• Usefulness — the reader can apply what they learned.
• Scannability — bullets and headings carry the structure; every key: value pair sits on its own line.
• Stories — points that must stick open with a short two-person story, names drawn from the persona roster and rotated between documents.
• Diagrams — flows, decisions, and lifecycles are drawn (per mermaid.md), each with a “what to notice” line.
• Quotability — every paragraph has at least one line a reader would underline.
• Accessibility — readable for non-native English speakers.
• References — sources cited and linked, and every link resolves (scripts/prose_lint.py checks this).
• Voice and grammar — scripts/prose_lint.py clean if Vale or Proselint is installed; no vague-difficulty words, weasel words, or unresolved grammar flags.