Technical Writing Rules

Technical writing exists to let someone accomplish a task without asking you a question — every sentence should either move them toward that task or get cut. Clever prose that doesn't reduce the reader's uncertainty is noise, not writing.

Audience first

• Identify the single most common reader before writing a word: a first-time user, an experienced integrator, or a maintainer reading the source. Write for that one reader — a doc trying to serve everyone at once serves no one well and bloats with caveats.
• State the reader's starting assumptions explicitly at the top ("this assumes you've already run setup.sh") rather than silently requiring context they may not have. An unstated assumption is where readers get stuck and give up.
• Match vocabulary to the audience's actual level — don't define HTTP for a doc aimed at backend engineers, and don't skip defining idempotent for one aimed at beginners. Misjudging this in either direction breaks trust fast.

One idea per sentence

• Write one claim, one step, or one fact per sentence. A sentence with "and" or "which" joining two separate ideas is usually two sentences that got merged under time pressure.
• Keep sentences short enough to scan, not necessarily short in an absolute sense — a 25-word sentence with one clear idea reads faster than two 12-word sentences that fragment a single thought awkwardly.
• Avoid stacking qualifiers and exceptions into the main sentence ("Do X, unless Y, in which case Z, though this doesn't apply if..."). Put exceptions in a separate sentence or a note, so the main path stays readable.

Examples over abstraction

• Show a concrete example before or immediately after any abstract rule. "Use kebab-case for filenames" plus a real filename teaches faster than the rule alone, and disambiguates edge cases prose can't fully specify.
• Prefer a working, copy-pasteable example over a partial snippet with placeholders like <your-value-here> scattered through it — readers copy what's on the screen, so make the screen correct.
• When a concept has a common failure mode, show the failure alongside the fix ("this breaks when X; do Y instead") rather than only describing the correct path in isolation.

Structure

• Lead each section with its conclusion or the action the reader needs, then support it — not a windup that makes the reader infer the point from context.
• Use headings that describe content specifically ("Configuring the retry timeout") over generic ones ("Configuration", "Overview") a reader can't scan for.
• Keep a consistent shape across parallel sections (e.g. every endpoint doc has Parameters, Response, Errors, in that order) so readers learn the doc's structure once and then navigate by pattern-matching.
• Put prerequisites, warnings, and version caveats before the steps they affect, never after — a reader who hits a warning after already breaking something has already paid the cost the warning was meant to prevent.

Terminology consistency

• Pick one term per concept and use it everywhere in a given doc set — don't alternate between "user" and "customer" and "account holder" for the same entity. Inconsistent terms make readers wonder if they're different things.
• Match the terminology the product or codebase actually uses, not a more "natural-sounding" synonym — a doc that says "workspace" when the UI says "project" creates friction at the exact moment the reader is cross-referencing the two.
• Define a term once, on first use, and never redefine it differently later in the same doc set.

What to cut

• Cut background, history, and motivation the reader doesn't need to complete the task at hand — link to it instead of inlining it, or move it to a separate "Concepts" page.
• Cut hedging phrases ("it should generally work," "in most cases") unless the uncertainty itself is the useful information — if it's not, state the behavior as a fact.
• Cut restating what a code block already shows in prose immediately below it — pick one, usually the code, and let a short caption carry any remaining context.
• Cut marketing language ("powerful," "seamless," "cutting-edge") from technical docs entirely — it carries no instructional value and reads as filler to a reader trying to get something done.

Reviewing your own draft

• Read the doc as if you are the target reader hitting it for the first time, mid-task, with no other context — not as the person who already knows how the system works.
• For every paragraph, ask what action or understanding it enables; if the answer is "none," cut it or move it to an appendix.
• Check that every code sample, command, and version number in the doc is one you have actually run or verified, not one written from memory.