# Grammar

From the Google developer documentation style guide; each section names its
source page.

Guide content © Google, used under CC BY 4.0
(https://creativecommons.org/licenses/by/4.0/).

## Contents

- [Voice](#voice)
- [Tense](#tense)
- [Person and mood](#person-and-mood)
- [Pronouns](#pronouns)
- [Agreement and plurals](#agreement-and-plurals)
- [Possessives](#possessives)
- [Contractions](#contractions)
- [Anthropomorphism](#anthropomorphism)
- [Articles](#articles)
- [Prepositions](#prepositions)
- [Sentence structure](#sentence-structure)

## Voice

Source: https://developers.google.com/style/voice

Active voice, with the actor named. Passive hides who acts, so the reader can't
tell whether they, the server, or the tool is responsible.

| Recommended | Not recommended |
|---|---|
| Send a query to the service. The server sends an acknowledgment. | The service is queried, and an acknowledgment is sent. |
| | The service is queried by you, and an acknowledgment is sent by the server. |

Passive is correct in three cases:

- The object matters more than the action: "The file is saved."
- The actor is the reader and naming them would accuse them: "Over 50 conflicts
  were found in the file" beats "You created over 50 conflicts in the file."
- Nobody needs to know who acted: "The database was purged in January."

## Tense

Source: https://developers.google.com/style/tense

Present tense for behavior that isn't tied to a moment.

| Recommended | Not recommended |
|---|---|
| Send a query to the service. The server sends an acknowledgment. | ...The server will send an acknowledgment. |
| If you send an unsubscribe message, the server removes you from the mailing list. | You can send an unsubscribe message. The server would then remove you from the list. |

`will` is right for something that genuinely happens later: "The file will be
archived the next time the backup process runs." Also for asynchronous work: "A
message is sent that will notify any Pub/Sub subscribers."

## Person and mood

Source: https://developers.google.com/style/person

Second person. Address the reader as "you", never as "the user" when you mean
them.

| Recommended | Not recommended |
|---|---|
| The following sections describe how you can create a website. | The following sections describe how we can create a website. |
| Consider adding a description to your table. | Let's add a description to our table. |
| This document shows you how to develop an app for your organization. | This document shows the user how to develop an app for their organization. |

Instructions take the imperative, with "you" implied: "Click **Submit**."

First person plural is for a real organization with an unambiguous antecedent:
"Example Organization provides A and B, but we don't provide C and D." The guide
limits first person singular to author commentary and FAQs.

One extension: documentation has no author present, but a status report does. When
you report work you did, "I changed both call sites" is correct and clearer than
passive voice. Past tense for the actions, present tense for the behavior that
resulted.

Third person describes what the software or an end user does, not what the
reader does.

## Pronouns

Source: https://developers.google.com/style/pronouns

Singular *they*, *them*, *their*. Not *he/she*, not *(s)he*.

Every pronoun needs an unmistakable antecedent. Where there's any doubt, repeat
the noun.

| Recommended | Not recommended |
|---|---|
| If you type text in the field, the text doesn't change. | If you type text in the field, it doesn't change. |
| Make sure that the ad is targeted. | Make sure that it's targeted. |
| Set this value to true. | Set this to true. |

Follow *this* and *these* with a noun. Keep *that* and *which*: "Right-click the
link that you want to open," not "the link you want to open."

*that* introduces a restrictive clause, no comma. *which* introduces a
nonrestrictive clause, with a comma: "The echidna, which has a long snout, is
furry."

## Agreement and plurals

Source: https://developers.google.com/style/pluralization

- *one or more* takes a plural verb: "If one or more tests fail, a system warning
  is triggered."
- *more than one* takes singular: "You can create more than one instance at a
  time."
- Compound subjects joined by *and* take plural: "The request payload and header
  information are logged."
- Pluralize acronyms as plain words: "APIs, IDEs". Never "API's". Add *es* after
  *s*, *sh*, *ch*, *x*: "OSes".
- Match number between the spelled-out term and the abbreviation: "virtual
  machines (VMs)", not "(VM)".
- Don't pluralize a unit after a number: "64 GB", not "64 GBs".
- Don't pluralize class names: "`Intent` objects", not "`Intent`s".
- No optional plurals in parentheses: "To find your API key, visit the
  **Credentials** page," not "your API key(s)".

## Possessives

Source: https://developers.google.com/style/possessives

Singular nouns take *'s*, including those ending in *s*: "the storage class's
quota". Plural nouns ending in *s* take a bare apostrophe: "the models'
capabilities".

Rewrite awkward possessives: "the rule that the Federal Trade Commission (FTC)
issued" rather than "the FTC's rule".

Don't form the possessive of a product name when describing what it does:
"Monitor Google Search performance", not "Monitor Google Search's performance".

Never form the possessive of a code item: "the `wordCount` method's return
value" is acceptable, "`wordCount`'s return value" is not.

## Contractions

Source: https://developers.google.com/style/contractions

Common two-word contractions are fine and preferred: *you're*, *don't*,
*there's*, *isn't*, *can't*. Negative contractions especially: *don't* is harder to misread than *do not*.

Avoid invented forms (*guides're*, *browser's* meaning "browser is") and
three-word contractions (*mightn't've*).

## Anthropomorphism

Source: https://developers.google.com/style/anthropomorphism

Don't give software or hardware human qualities.

| Recommended | Not recommended |
|---|---|
| A Delimiter object specifies where to split a string. | A Delimiter object tells the splitter where a string should be broken. |
| The PC detects a new device. | The PC sees a new device. |

Software doesn't want, think, know, see, try, or decide. Nor does it get confused
or get upset.

## Articles

Source: https://developers.google.com/style/articles

Include *a*, *an*, and *the*. Don't drop them for brevity, not even in headings
and titles. They help comprehension and translation. "Create a VM instance", not
"Create VM instance".

Choose *a* or *an* by how the following word is pronounced, not how it's
spelled: "a SQL database", "a FHIR resource", "an SAP system".

For *the* before a product name, see `names.md`.

## Prepositions

Source: https://developers.google.com/style/prepositions

Ending a sentence with a preposition is fine and often clearer: "see the client
library documentation for the language you're interacting with" beats "...the
language with which you're interacting."

Include prepositions that add clarity, drop the ones that don't, and don't chain
so many that the sentence loses its subject. For which preposition goes with
which UI element, see `code.md`.

## Sentence structure

Source: https://developers.google.com/style/sentence-structure

- Conditions and circumstances before instructions: "To delete the entire
  document, click **Delete**."
- Under 26 words per sentence, per the accessibility guidance.
- Prefer the simple verb to the phrasal verb: "This document uses the following
  terms," not "makes use of". Established phrasal verbs stay: *set up*, *log in*,
  *sign in*.
- At most two nouns stacked as modifiers, unless the stack is the established
  name of the thing (*payment retry queue*).
- Place *only* immediately before what it limits: "Request only one token," not
  "Only request one token."
- Keep helper words *then*, *that*, and *of*: "If the value isn't found, **then**
  the default is returned."
- Repeat a word when it prevents a misreading: "both IAM segmentation and network
  segmentation".
- Name the type of thing along with its identifier: "the `example.yaml` file".
- Minimize negative constructions, and never stack two.
- Don't use one word for two meanings in the same document.