Technical Writing Style Guide for AI Agents

# Technical Writing Rules Apply these rules to every doc, README, or guide you write or edit. When editing existing prose, fix violations in the sentences you touch; do not rewrite untouched paragraphs. ## Voice and sentences - Active voice, present tense: "The scheduler retries failed jobs", never "Failed jobs will be retried". Passive voice is allowed only when the actor is genuinely unknown or irrelevant. - Address the reader as "you". Never "the user", "one", or "we" (except "we" for explicit project decisions: "We chose SQLite because..."). - Hard limit: 25 words per sentence. If a sentence needs "which", "and also", or a second comma to survive, split it. - One idea per paragraph, four sentences maximum. A paragraph that needs a sixth sentence is two paragraphs. - Delete hedges and filler on sight: "simply", "just", "easily", "note that", "it should be noted", "in order to" (→ "to"), "basically", "various". If a step is genuinely simple, the reader will notice without being told. - Define every acronym at first use, even common ones, unless it appears in the project's own name. - Concrete numbers over vague claims: "responds in under 50 ms" not "responds quickly"; "supports files up to 2 GB" not "supports large files". ## Code samples - Every code sample must run as written. No `...` ellipses inside code, no undeclared variables, no pseudo-imports. If context is required, include it or state the precondition in one line above the block. - Every fenced block declares its language (` ```bash `, ` ```python `). Shell samples show the command only — no `$` prompt prefix — so readers can copy-paste. - Show expected output after commands whose output matters, in a separate block labeled with a one-line lead-in: "This prints:". - Placeholders use angle brackets and a noun: `<your-api-key>`, `<region>`. Never `xxx`, `foo` for real values, or fake-but-plausible secrets. - One concept per sample. A sample that demonstrates auth and pagination and error handling is three samples. - Keep samples under 20 lines; link to a full example file for anything longer. ## Headings and structure - Headings answer the reader's question, in sentence case: "Configure the database connection", not "Database Configuration Overview" and not "Configuring The Database". - Never skip levels (`##` to `####`), never use a single child heading (a section with one subsection needs no subsection), never go deeper than `###`. - The first paragraph under any H1 states what the thing is and who needs it, in two sentences, before any badge, table, or feature list. - READMEs follow this order: what it is, install, smallest working example, configuration, links to deeper docs. Contributing and license go last. - Use numbered lists only for sequences the reader performs in order; bullets for everything else. A step in a numbered list starts with a verb. - Tables for lookup data (flags, env vars, error codes) with at most four columns; prose for explanation. Never explain in a table or tabulate an explanation. ## Editing existing docs - Preserve the document's existing terminology even when synonyms exist — if the doc says "workspace", do not introduce "project" for the same concept. - When a doc contradicts the code, fix the doc to match the code and say so in your summary; never paper over the gap with vaguer wording. - Update every cross-reference and table of contents entry affected by a heading change in the same edit. - Prefer deleting an outdated section to marking it "(deprecated)" — stale instructions are worse than missing ones.