# Grammar and mechanics detail

Detail for: articles, contractions, pluralization, possessives, prepositions,
pronouns, tense, sentence structure, reference verbs, anthropomorphism, italics.
Source: developers.google.com/style (Articles, Contractions, Pluralization,
Possessives, Prepositions, Pronouns, Tense, Sentence structure, Reference verbs,
Anthropomorphism, Italics for terms).

## Articles (a, an, the)

- Always include articles — never drop them for brevity, including in headings.
  - Recommended: Create **a** VM instance — Not: Create VM instance
- Use `a` when the next word starts with a consonant **sound**, regardless of
  spelling. For abbreviations whose pronunciation varies, choose the article to
  match the common pronunciation (e.g., "an SQL database" if you pronounce it
  "ess-queue-ell", "a SQL database" if you say "sequel").

## Contractions

- Use contractions, especially negations: *isn't*, *don't*, *can't*. Readers
  can miss the word *not* when scanning.
- Don't invent nonstandard contractions (*guides're*, *browser's* for "browser
  is") or three-word contractions (*mightn't've*).
- To emphasize a negation you can use formatting, e.g. "is **_not_**".

## Pluralization

- Make subject and verb agree, especially with long or complex subjects:
  - Recommended: "The number of entries listed in the directory **is** accurate."
  - Recommended: "The request payload and header information **are** logged."
- In product names, don't pluralize (they're proper nouns): "use Project
  IDs" — check the word list for specific entries.
- For plural of code elements, don't inflect the code name; add a noun instead
  ("multiple `config` files", not "multiple configs").
- Don't use parentheses for optional plurals ("file(s)") — see word list
  nuance; in general rewrite instead.

## Possessives

- Singular nouns (including ones ending in s): add `'s` — "each vector's
  record".
- Plural nouns ending in s: add only `'`: "the developers' guide".
- Don't form possessives from product, feature, or company names when
  describing their function; use the name as a modifier or rephrase with *of*:
  - Recommended: "the Cloud Console menu" — Not recommended: "Cloud Console's menu"
- Trademarks: never form a possessive. "Chromebook" → "Chromebook's features"
  is wrong.
- Code items: avoid possessives entirely; "the value of the `ADDRESS` constant",
  not "`ADDRESS`'s value".

## Prepositions

- Include prepositions that increase clarity, omit unnecessary ones, and don't
  clutter sentences.
  - Recommended: "the client library documentation **for** the language you're
    interacting with"
  - Not recommended: "...the language with which you're interacting."
- In cross-references use *about*, not *on*: "For more information about
  indexes, see ..."

## Pronouns

- Ensure a pronoun clearly refers to its antecedent; if ambiguous, repeat the
  noun.
  - Recommended: "If you type text in the field, the text doesn't change."
  - Not recommended: "...it doesn't change."
- After a demonstrative (`this`/`these`/`that`), include a noun: "Set this
  value to true", not "Set this to true".
- Gender-neutral: use singular *they*; never *he/she*, *(s)he*, or generic *he*.
- Use second person (*you*) for the reader; first person (*I* in FAQs, *we* for
  the organization) only in specific contexts.
- `that` for restrictive clauses, `which` (with comma) for nonrestrictive:
  "the option that you selected", "the option, which is deprecated, ...".

## Tense

- Present tense for general behavior: "The server sends an acknowledgment",
  not "will send".
- Future tense (*will*) only to flag a genuinely future action: "The file will
  be archived the next time the backup process runs."
- Don't use future tense for how a feature will work after a future release
  (write it as current behavior instead — see `reference/strategy.md`).
- Avoid hypothetical *would*: "If you send an unsubscribe message, the server
  removes you from the list" — not "You can send... The server would then...".

## Sentence structure

- Put conditions before instructions, and the most important information first.
  - Recommended: "If your app is located in one of the following regions, ..."
  - Not recommended: "...if your app is located in one of the following regions." (buried at the end)
- Use "For more information, see [link]." rather than "See [link] for more
  information."
- "To delete the entire document, click Delete." rather than "Click Delete if
  you want to delete the entire document."
- Keep sentences short, vary the openings.

## Reference verbs (API descriptions)

- In API reference descriptions, the first verb matches the reference style:
  says *creates*/*returns* (describes what the method does) vs *create*/*return*
  (imperative instruction). Follow the existing style of the reference:
  - "tasks.insert: Creates a new task on the specified task list."
- Use a parallel, consistent form throughout a reference.

## Anthropomorphism

- Don't have software or objects do human actions: *see, think, feel, want,
  believe, tell, assume*, etc.
  - Recommended: "A Delimiter object specifies where to split a string."
  - Not recommended: "A Delimiter object tells the splitter where a string
    should be broken."
  - Recommended: "The PC detects a new device."
  - Not recommended: "The PC sees a new device."
- Exception: standard idioms in technical vocabulary are fine when the product
  uses them (e.g., "the server returns a 404", "the API expects a JSON body").

## Italics for terms (words as words)

- **New terms**: italicize on first mention when defining immediately. Don't
  use bold or quotes: "A *Clos* network is a kind of multistage circuit
  switching network."
- **Words as words**: italicize when referring to the word itself: "Use the
  word *and* instead." Don't use bold or quotation marks.
- **Titles of full-length works**: italics (*The Chicago Manual of Style*).
  Short works get quotation marks.
- Don't use italics for emphasis in running text; prefer plain words or
  reordering.