technical-documentation

# Technical Documentation

Audit, write, and improve developer documentation the way Google's technical writers do: start from the reader's task, verify every fact against the code, then apply the style guide in severity order — structure before voice, voice before word choice.

## Core Principle

**Write for the reader's task, not the product's feature list.** Google's guide asks for prose that is conversational but not frivolous, precise, and consistent, because a developer reading docs is trying to get something done, not to admire the product. Two framing rules from the guide shape everything below:

- **Guidelines, not rules.** Depart from the guide when doing so improves the content — established domain terminology wins — but stay consistent within the document.
- **Precedence.** A project's own style guide comes first, then Google's guide, then Merriam-Webster (spelling), the Chicago Manual of Style (general style), and the Microsoft Writing Style Guide (technical style).

Rules come in two layers. Structural and content rules (headings, procedures, code samples, second person, active voice, timeless docs, accessibility) apply to documentation in any language. Rules tagged `[EN]` (spelling, serial comma, contractions, the word list) apply only to English text — skip them for other languages, and never translate a document unless asked.

## Scoring

**Goal: 10/10.** Score = number of Quick Diagnostic rows passed (10 rows, 1 point each; the `[EN]` row auto-passes for non-English docs). Bands: **9-10** = ships as is; **7-8** = word- and voice-level edits only; **5-6** = restructure sections, then re-edit; **≤4** = rewrite from the doc-type skeleton. Blocking findings — wrong or unverifiable facts, a procedure that can't be completed, information that exists only in an image or in an image without alt text — are a separate gate: the doc is **not shippable** at any score until they're fixed. Report the score, the failed rows, and the exact edits that reach 10/10.

## Framework

### 1. Know the Reader and the Document's Job

**Core concept:** Every page serves one reader with one task. Name both before writing a word — audience and level, what they'll be able to do afterwards — and pick the document type that fits: tutorial (learn by doing), how-to (accomplish a task), concept (understand), reference (look up), README (orient and start).

**Why it works:** Readers scan for their task; a page that mixes concept, procedure, and reference forces them to read everything to find anything.

**Key insights:**
- Google's Technical Writing course opens a doc with an audience statement and a scope plus non-scope statement — the non-scope rescues readers who are on the wrong page
- "Before you begin" lists prerequisites before step 1, not inside step 4 (convention)
- Key points first: the intro states what the reader gets, not the product's history
- Every procedural page ends with verification ("Confirm that…") and "What's next" (convention)

**Applications:**

| Context | Application | Example |
|---------|-------------|---------|
| README | Orient: what it is, who it's for, three-step start, links out | Purpose → install → first run → docs map |
| Mixed page | Split concept from procedure into linked pages | "How OAuth works" + "Configure OAuth" |
| Tutorial vs how-to | Tutorial teaches one path end to end; how-to assumes context | "Build your first plugin" vs "Add a hook" |

See [references/document-types.md](references/document-types.md) when choosing or restructuring a doc type — skeletons for README, getting started, tutorial, how-to, and concept pages, the audience and scope statements, and the self-editing pass for large doc sets.

### 2. Voice: You, Active, Present, Timeless

**Core concept:** Address the reader as "you", make the actor of every sentence explicit, describe behavior in the present tense, and write as if the page will be read in five years.

**Key insights:**
- "We" hides who acts; "the user" turns the reader into a third party — both weaken an instruction
- Passive voice is allowed only when the actor is unknown or irrelevant ("The file is encrypted at rest")
- "Will" belongs only to genuinely later effects: "The server sends an ack", not "will send"
- Contractions are fine — Google prefers "isn't" over "is not" for negations `[EN]`
- Software doesn't want, see, or think: "The API detects", not "the API sees"
- No "please" (reserve it for asking permission), no "simply / easily / just", no superlatives — if a step is easy, the reader will notice
- Timeless: cut "currently", "new", and "soon"; never pre-announce unreleased features

**Before → after:**
- "Please note that the new dashboard will simply be shown once the user has logged in." → "After you sign in, the dashboard appears."
- "We recommend that the token is refreshed by the client." → "Refresh the token from the client."

See [references/voice-and-words.md](references/voice-and-words.md) when a doc's tone is off or inconsistent — the voice rules with the guide's exact exceptions, inclusive and global-audience language, and the full word list.

### 3. Sentences and Words

**Core concept:** Put the condition before the instruction, keep one idea per sentence, and choose the plain word the guide's word list prefers.

**Key insights:**
- "To delete the document, click **Delete**" — readers decide whether a step applies before they act, not after
- Spell out an abbreviation on first use with the short form in parentheses; skip only universally known ones (URL, HTML)
- Latin abbreviations translate and scan poorly: "for example", not "e.g."; "that is", not "i.e."; omit "etc." or finish the list `[EN]`
- "can" = ability, "may" = permission, "might" = possibility `[EN]`
- Word list samples `[EN]`: sign in (not log in) · set up as a verb · lets you (not allows you to) · through or by using (not via) · after (not once) · use (not leverage or utilize) · checkbox · email
- Jargon is fine for the stated reader and a defect