technical-documentation

Files (8)

• SKILL.md
• api-reference.md · references/
• audit-checklist.md · references/
• document-types.md · references/
• procedures-and-code.md · references/
• release-notes.md · references/
• structure-and-formatting.md · references/
• voice-and-words.md · references/

SKILL.md (first lines)

# 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 for anyone else — define it or link it

**Before → after:**
- "Click Save in order to persist the settings once you are done, i.e. when all fields are filled." → "After you fill in all fields, click **Save**."
- "The CLI utilizes the GCP SDK (e.g. for auth)." → "The CLI uses the Google Cloud SDK, for example for authentication."

See [references/voice-and-words.md](references/voice-and-words.md) when auditing word choice — the word list table (avoid → use → why), abbreviation rules, and modal verbs.

### 4. Structure: Headings, Lists, Tables, Notices

**Core concept:** Structure is the reader's map. Headings in sentence case read as a table of contents; lists carry parallel items introduced by a full sentence; tables have header rows; notices are rare and mean something.

**Key insights:**
- Task headings are bare imperatives ("Create an instance"); concept headings are noun phrases ("Instance lifecycle"); no "-ing" headings
- A list needs an introductory sentence ending in a colon, and every item in the same grammatical form; numbered only when order matters
- Description lists (term → definition) beat two-column tables for paired data
- Tables: header row, an intro sentence, no merged or empty cells — screen readers depend on it
- Note = useful but optional; Caution = proceed carefully; Warning = harm or irreversible loss. Don't stack them; one per section is a practical ceiling (inferred)
- Cross-references say "see", never "above" or "below" — pages reflow and get translated
- Link text names the target ("see Configure a custom domain"), never "click here"
- Alt text states the image's purpose; information must never live only in a picture

**Applications:**

| Context | Application | Example |
|---------|-------------|---------|
| Wall-of-text page | Insert a task heading wherever the task changes | "Install", "Configure", "Verify" |
| Three stacked notes | Fold two into body text; keep the one that changes behavior | One **Caution** about data loss |
| Options table | Header row + intro sentence + parallel cell phrasing | "The following flags control output:" |

See [references/structure-and-formatting.md](references/structure-and-formatting.md) when fixing page structure — heading, list, table, notice, cross-reference, link-text, image, number, and date rules with before/after pairs.

### 5. Procedures and Code

**Core concept:** A procedure is a numbered list of single imperative actions, each stating where to act and what to expect. Code is set in code font, introduced by a sentence ending in a colon, and uses placeholders the reader can't mistake for literals.

**Key insights:**
- One action per step; "Optional:" prefix for optional steps; a single step is a bullet, not "1."
- Sub-steps run a, b, c; document the shortest path, not every alternative
- UI element names in bold, matching on-screen casing; click for a mouse, tap for touch, select when device-agnostic
- Code font for filenames, paths, commands, flags, parameters, and values — not for product names
- Placeholders are `ALL_CAPS_WITH_UNDERSCORES`, never `<your-key>` or `YOUR_API_KEY`, and are explained right after the sample ("Replace `PROJECT_ID` with…")
- Command syntax: `[optional]`, `{a|b}` for exclusive choices, `...` for repeatable arguments
- Samples are runnable, minimal, wrapped at 80 characters, and show the expected output

**Before → after:**
- "Run the command below with your key: `shipit deploy --key=<your-key>`" → "To deploy, run the following command:" → fenced `shipit deploy --key=API_KEY` → "Replace `API_KEY` with the key from the **Settings** page."
- "1. You should now click on the Deploy button to deploy." → "1. Click **Deploy**. The status changes to **Deploying**."

From wondelai/skills, MIT.

More from wondelai/skills