---
name: google-style-guide
description: Applies Google Developer Documentation Style Guide principles (second person, active voice, present tense, plain language, sentence case, formatting, code conventions, and word choices). Use when writing, editing, or reviewing developer documentation, READMEs, API docs, code comments, or technical communications, or when requested to follow Google style.
license: CC-BY-4.0
---

# Google developer documentation style

This skill distills the [Google developer documentation style guide](https://developers.google.com/style) into actionable rules for writing and reviewing technical documentation and developer communications.

**How to use this skill:**
- **Technical artifacts (docs, READMEs, API guides, design docs, code comments):** Follow the full style guide rules and formatting conventions below.
- **Conversational messages / agent responses:** Apply the core principles (clarity, brevity, active voice, second person, no fluff or marketing hype) while keeping interactions natural.
- **Reviewing existing text:** Identify deviations, quote the original snippet, explain the issue plainly, and provide the corrected version. Follow these principles in your own review comments as well.
- **Resolving paths:** Reference files and scripts reside in this skill's directory. Resolve all paths relative to that directory.

## Core rules

1. **Be conversational and friendly without being frivolous.** Sound like a knowledgeable friend, not a textbook and not a hype machine. No slang, no exclamation marks, no internet abbreviations (`tl;dr`, `ymmv`).
2. **Address the reader as *you*.** Use imperative mood for instructions ("Click Save", "Run `npm install`"). Use *we* only for the organization you belong to, *user* only for the user of software your reader is developing.
3. **Use active voice.** Make the doer the subject: "Send a query to the service. The server sends an acknowledgment." Passive voice is acceptable only to emphasize the object ("The file is saved"), de-emphasize the actor, or when the actor is unknown.
4. **Use present tense.** "The server sends an acknowledgment", not "will send". Reserve future tense for actions that genuinely happen later. Avoid *would*.
5. **Write plainly and simply.** Short sentences, common words, no jargon, clichés, or culturally specific references. Write for a global audience that may read in translation.
6. **Put conditions before instructions, and key information first.** "If your app is in one of these regions, expect latency" before the action.
7. **Use standard American spelling and punctuation** (serial/Oxford comma included).
8. **Be accurate and honest.** Do not exaggerate. Avoid superlatives like *best, fastest, never, always*; be careful with *ensure* and *guarantee*. Do not claim things that a future release or incident could invalidate.

## Voice and tone

- Aim for conversational but not formal: "This API lets you collect data about what your users like" — not "Dude! This API is totally awesome!" and not "The API documented by this page may enable the acquisition of information."
- Skip the fluff: do not pre-announce ("In this section, we will..."), and avoid filler phrases like *please note*, *at this time*, *simply*, *it's easy*, or *quickly*.
- Avoid figurative language and ableist metaphors ("the PC **sees** a new device" → "the PC **detects** a new device").
- Do not overuse *please* in instructions. "To view the document, click View", not "please click View".
- Vary sentence openings; avoid starting every sentence with "You can" or "To do".

## Language and grammar essentials

| Topic | Rule | Example |
|---|---|---|
| Articles | Always include *a/an/the* — do not drop them for brevity | "Create a VM instance", not "Create VM instance" |
| Contractions | Use them, especially negations (*don't*, *can't*, *isn't*) — easier to read | "Don't use..." |
| Pronouns | Clear antecedents; singular *they* for gender-neutral; no *he/she* | "If you type text in the field, the text doesn't change" (not "...it doesn't change") |
| Tense | Present; future only for real future actions | "The file will be archived next time the backup runs" |
| Numbers | Spell out zero–nine; numerals for 10+; spell out ordinals (*first*, not *1st*); sentence-starting numbers spelled out | "five minutes", "15 directories", "the twelfth step" |
| Capitalization | Sentence case in titles/headings; do not capitalize unnecessarily; do not rely on caps to convey meaning | "Create an instance", not "Create an Instance" |
| Abbreviations | Spell out on first use with acronym in parentheses, then use acronym alone; no periods in acronyms | "Google Kubernetes Engine (GKE)" |

Put conditions before instructions: "If you run out of space, delete the unused files" before "Delete unused files".

## Punctuation essentials

- **Serial comma**: Always use the serial (Oxford) comma in lists of three or more: "zones, regions, and multi-regions".
- **Colons**: Introduce lists only after a complete sentence ("The fields are defined as follows:", not "The fields are:").
- **Periods**: End sentences with periods. Place periods inside quotation marks ("like this."), even when not part of the quoted material (standard American style).
- **Hyphens**: Use for compound modifiers before a noun ("a two-day total").
- **Dashes**: Use em dash (—) without spaces around it. Do not use an em dash where a colon or period works.
- **Avoid**: Ellipses (…), semicolons where a period or comma works better, slashes for alternatives (write out *and* or *or*), and exclamation marks.

## Formatting and organization

- **Headings/titles**: Sentence case for all headings and titles. Task headings start with a bare infinitive ("Create an instance", not "Creating an instance"); concept headings are noun phrases. No links, code font, or sequence numbers in headings.
- **Lists**: Numbered for sequential steps, bulleted for non-sequential items, definition lists for term–definition pairs. Introduce lists with a complete sentence. Keep list items parallel in structure.
- **Links**: Descriptive link text (page title or descriptive phrase), never "click here" or a bare URL. "For more information, see X." Link to relevant destinations without opening new tabs.
- **UI elements**: Bold visible UI labels ("click **Save**"). Do not use UI elements as verbs ("save the settings" → "click **Save**").
- **Code in text**: Use code font (backticks) for filenames, paths, commands, class/method names, literals, and environment variables. Never inflect code as English ("send a POST request", not "POST the data"). Place a descriptive noun after the code item ("the `pg_hba.conf` file").
- **Numbers & units**: Use a nonbreaking space between number and unit ("64 GB"). Use 12-hour clock ("3 PM", "3:45 PM"). Spell out months in dates ("January 19, 2017"); use ISO 8601 (`YYYY-MM-DD`) only for numeric-only tables/logs.
- **Images**: Provide descriptive alt text (≤155 characters, no "Image of..."); use empty `alt=""` for decorative images. Introduce images with a complete sentence.
- **Procedures**: Numbered steps, each starting with an imperative verb. Put location before action ("In the Google Cloud console, go to the BigQuery page"). State the goal before the action.
- **Notices** (Note/Caution/Warning): Use sparingly. Do not stack multiple notices. Use notes only for non-critical asides.
- **Tables**: Use for three or more related pieces of data per item. Provide a complete-sentence introduction and clear column headers. Do not use tables for layout.

## Applying the style per medium

- **Docs / READMEs / Design docs**: Full rules above. Structure with descriptive headings, put the most important information first, and keep paragraphs focused on a single topic (5–6 sentences maximum).
- **Code comments**: Plain sentences explaining *why* rather than restating what the code does. Use present tense or imperative mood.
- **Commit messages** *(developer house convention)*: Imperative, present-tense summaries ("Add retry logic", not "Added retry logic" or "Adding retry logic").
- **Chat replies / Agent messages**: Direct and conversational. Short sentences, active voice, second person. Skip pleasantry fluff, hype, and filler phrases like "please note".
- **Reviewing text**: Quote the original text, state the rule or issue clearly, and provide the exact revised phrasing.

## Word list lookup

The companion file `word-list.md` contains 587 specific term guidelines, preferred spellings, and terms to avoid.

> **CRITICAL**: Do **NOT** read `word-list.md` in full with the `read` tool (it is 114 KB / 1,700 lines and exceeds tool truncation limits).

To check a specific word or term:
```bash
# Use the helper script in the skill directory:
"$SKILL_DIR/lookup-word.sh" "<term>"

# Or search directly with grep/rg:
grep -i -C 2 -E "(^|\*\*)$TERM(\*\*|\[|$)" "$SKILL_DIR/word-list.md"
```

## Review checklists

### Quick check (chat replies & short answers)
- [ ] Direct, conversational, and helpful without fluff, hype, or exclamation marks?
- [ ] Active voice and second person ("you" / imperative mood for steps)?
- [ ] Plain language with clear antecedents and no unexplained abbreviations?

### Comprehensive checklist (documentation, READMEs, PRs, design docs)
- [ ] Conversational and friendly without exclamation marks, slang, or hype?
- [ ] Second person ("you") used throughout; imperative mood for instructions?
- [ ] Active voice used; any passive construction justified?
- [ ] Present tense used (except for actions that genuinely occur in the future)?
- [ ] Plain words used; jargon avoided; abbreviations spelled out on first mention?
- [ ] Conditions placed before instructions; key information stated first?
- [ ] Serial (Oxford) comma used; punctuation inside quotation marks; no unnecessary semicolons/slashes/ellipses?
- [ ] Numbers and units formatted correctly (0–9 spelled out, 10+ numerals, space before units)?
- [ ] Sentence case used for all headings; task headings start with bare infinitives?
- [ ] UI labels bolded; code elements backticked and never inflected as English?
- [ ] Accurate and honest; no unsupported superlatives or excessive claims?
- [ ] Unsure terms checked against `word-list.md` via `./lookup-word.sh <term>`?

## Topic reference index

For deep-dive rules on specific topics, read the individual reference files located in `reference/`:

| Topic | Reference file |
|---|---|
| Word choice, usage, spelling ("is it *log in* or *login*?") | `word-list.md` *(use `./lookup-word.sh`)* |
| Grammar detail (articles, possessives, plurals, prepositions, tense, pronouns, anthropomorphism) | `reference/grammar.md` |
| Punctuation detail (colons, commas, dashes, hyphens, quotes, semicolons) | `reference/punctuation.md` |
| Formatting detail (headings, lists, tables, notices, links, images, procedures, UI elements) | `reference/formatting.md` |
| Code and API docs (code font rules, syntax, placeholders, API comments, Markdown/HTML) | `reference/code.md` |
| Numbers, units, dates/times, abbreviations, trademarks, jargon, claims | `reference/technical.md` |
| Accessibility, inclusive language, translation & global audience | `reference/accessibility.md` |
| Documentation philosophy, prescriptive writing, timelessness, citations | `reference/strategy.md` |
| Authoritative live guide | https://developers.google.com/style *(if web access is available)* |

## Attribution and currency

- **Source**: Derived from the [Google Developer Documentation Style Guide](https://developers.google.com/style), licensed under [Creative Commons Attribution 4.0 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
- **Currency**: Last verified against the live guide on 2026-08-19.