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:

See 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 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 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:

See 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."

See references/procedures-and-code.md when writing steps or samples — the full procedure rules, UI-element and device verbs, code-in-text, placeholder, command-line syntax, and the sample-code quality checklist.

6. Reference Docs: API, Docstrings, CLI Help

Core concept: Reference text is descriptive, complete, and formulaic on purpose — readers look things up, so every entry must exist and read the same way.

Key insights:

• Document every public class, method, field, constant, and enum value; a missing entry reads as "unsupported"
• Open method descriptions with the category verb: "Gets the…", "Sets the…", "Checks whether…", "Creates a…", "Returns…" — never "This method…"
• Non-boolean parameters start "The…" or "A…"; booleans read "If true, … If false, …" (action) or "True if …; false otherwise" (state)
• Document return values and exceptions ("Thrown when…") for every method that has them
• A deprecated element names its replacement in the first sentence
• CLI --help (convention — Google has no --help page): usage line in [optional] syntax, one-line synopsis, every flag described with the same placeholder style

Before → after:

• "This method is used for getting the customer." → "Gets the customer for the given customerId. Throws NotFoundError when no customer exists."
• "@param force - force flag" → "@param force If true, deletes the bucket even if it contains objects. If false, fails when the bucket isn't empty."

See references/api-reference.md when writing or auditing reference material — the verb-by-category table, parameter, return, and exception patterns, one complete JSDoc example, and CLI help conventions.