Pronouns

Ambiguous pronoun references

Avoid vague and confusing references between a pronoun and its antecedent.

Examples

Not recommended: If you type text in the field, it doesn't change.

Recommended: If you type text in the field, the text doesn't change.

Not recommended: The name of the function to execute in the given script. It does not include parentheses or parameters.

Recommended: The name of the function to execute in the given script. The name does not include parentheses or parameters.

In many cases, it's best to use these types of words as adjectives modifying nouns instead of using them as pronouns.

Examples

Not recommended: Set this to true.

Recommended: Set this value to true.

Gender-neutral pronouns

Don't use gender-specific pronouns unless the person you're referring to is actually that gender.

In particular, don't use "he," "him," "his," "she," or "her" as gender-neutral pronouns, and don't use "he/she" or "(s)he" or other such punctuational approaches. Instead, use the singular "they."

Singular "they" has been in use for a long time; for example, Jane Austen used it, and in 2015 the Washington Post adopted it as part of their official style.

But if you really can't stand using singular "they," then rewrite to avoid singular gendered pronouns. Using plurals can often help. For more suggestions, see The Chicago Manual of Style, 16th edition, section 5.225, "Nine techniques for achieving gender neutrality."

Optional pronouns

Use optional pronouns, such as "that" and "who," to avoid ambiguity and clarify meaning in sentences.

Examples

Not recommended: Make sure all the files are correct.

Recommended: Make sure that all the files are correct.

Not recommended: Right-click the link you want to open.

Recommended: Right-click the link that you want to open.

Personal pronouns

Avoid first-person pronouns ("I," "we," "us," "our," and "ours") except in the following contexts:

  • The questions in FAQs.
  • A document whose author makes comments in the first person.
  • Using "we" to refer to your organization, after using your organization's name. For example, "Example Pet Store recommends that you feed your aardvark Standardized Aardvark Treats. We cannot guarantee the happiness of your aardvark otherwise."

Use the second-person pronoun ("you") whenever possible.

For more information about second person, see Second Person.

Relative pronouns

There are several relative pronouns. This section concerns only three of them: "that," "which," and "who."

"That" and "which" don't mean exactly the same thing, so don't substitute one for the other:

  • "That" introduces a restrictive clause. It isn't preceded by a comma.

    Example:

    Recommended: The echidna that has a long snout is furry.

    This sentence describes a particular echidna, the one that has a long snout.

  • "Which" introduces a nonrestrictive clause and is preceded by a comma.

    Example:

    Recommended: The echidna, which has a long snout, is furry.

    This sentence describes all echidnas, and mentions in passing that they all have long snouts.

For more information about restrictive and nonrestrictive clauses and whether to use "that or "which," read what Grammar Girl has to say on the subject.

When referring to a person, use "who," not "that."

Examples

Not recommended: Grant access to the authenticated user that provides an invitation token.

Recommended: Grant access to the authenticated user who provides an invitation token.

However, you can use "whose" to refer to people, animals, and things. "Whose" is the possessive form of both "who" and "which."

Example

Recommended: Examine the variables whose values are set at compile time.

Send feedback about...

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide