tech-writing

Tech Writing

House style for developer-facing prose, distilled from the complete Google developer documentation style guide. Almost every rule below exists for one of three reasons: accessibility (screen readers, keyboard users), translatability (a global audience with varying English proficiency), or speed (a reader in a hurry, scanning, mid-task). Keep those three reasons in mind and you can resolve cases no rule covers.

Two meta-rules outrank everything else:

• Project style wins. If the repo or team has its own conventions, follow those first.
• Clarity wins. The guide's own advice: break any of these rules sooner than write something unclear or awkward. Consistency within a document beats strict compliance.

How to work

1. Establish the mode. Writing new content, editing in place, or reviewing with feedback only. If the user asked for a review, report findings — don't rewrite unasked.
2. Identify the doc type — it changes the verb forms and heading style (see the next section).
3. Apply the core rules in this file; they fix most drafts.
4. Open reference files for depth only as the content demands them (routing table at the end). For any single-word dispute, grep the word list first — most arguments are already settled among its 598 rulings.

Doc types

Type	Verb form	Heading style
Task / how-to / tutorial	Imperative: "Click Submit."	Bare infinitive: "Create an instance" (never "Creating an instance")
Concept / overview	Declarative, present tense	Noun phrase: "Migration to Google Cloud" (never "-ing" first word)
Reference (API, CLI)	Third-person -s openers: "Creates a new task." (never "Create a new task.")	The element name

Core rules

Voice

• Second person. Address the reader as you. Never "the user" for the reader; never "let's". We only when it unambiguously means the authoring organization.
• Active voice, named actor. "The server sends an acknowledgment," not "an acknowledgment is sent." Passive is fine only when the actor is irrelevant ("The database was purged in January") or to avoid blaming the reader ("Over 50 conflicts were found").
• Present tense. No will for normal behavior; reserve it for genuinely later or asynchronous effects. Never hypothetical would — use "If you X, the server Ys."
• Conversational but precise — a knowledgeable friend, not a robot and not a clown. Use contractions, especially negative ones (don't is harder to misread than not). No humor, idioms, metaphors, pop-culture references, or exclamation points.
• Never promise ease. Delete simply, easily, just, quickly, "it's easy". What's simple for the author isn't simple for the reader.
• No "please" in instructions. "To view the document, click View." Politeness in docs is directness.
• Don't anthropomorphize. Software detects, receives, displays — it doesn't see, think, want, or know.