Grammar
Table of contents
Guidelines for building the grammatical machinery of a sentence.
Abbreviations
Abbreviations as verbs
Don’t use abbreviations or acronyms as verbs.
-
No: CNAME the domain.
-
Yes: Add the domain to your CNAME records.
Spell out abbreviations
If you’re using an abbreviation that isn’t well-known, use its full, unabbreviated form the first time it appears and provide its shortened form in parentheses. You can then use the shortened form throughout the rest of the document.
- Example: The Aperture Science Test Selection Dashboard supports single sign-on (SSO). To configure SSO for your team…
Active and passive voice
Active voice
Try to use the active voice (which focuses on the “do-er” of an action) whenever possible.
-
No: The data must be updated.
(Passive. Who needs to update the data? The user? The program itself? Someone else?) -
Yes: You must update your data before continuing.
(Active. The subject is you—the reader knows who must perform the action.) -
Also yes: Update your data.
(Also acceptable; imperative verbs are active and speak directly to the reader, which is useful for procedural instructions.)
Passive voice
However, there may be times when the passive voice is preferable, including: (1) to focus on the outcome or recipient of action rather than who’s performing it, (2) to avoid blaming the user for an error, or (3) when the reader doesn’t need to know who performed an action (in the case of an automatic process or backend system).
- Yes: Your password will be reset.
(Acceptable passive. Since the reader doesn’t need to do anything, the performer of the action is less important than its outcome.)
Pronouns
First-person pronouns
It’s okay to refer to Aperture Science with first-person pronouns like we or our. For best results, try to mention Aperture Science by name at least one time before using a pronoun in its place.
- Example: Aperture Science does not collect information about your age or date of birth. But if we did, we might throw you a surprise party.
However, there may be times when it’s clearer to refer to Aperture Science by name, especially if you need to specify the name of our product or company.
- Example: This feature prevents a conflict between Black Mesa’s integration and Aperture Science’s backend.
Second-person pronouns
When addressing the reader, it’s okay to use second-person pronouns like you and your. Don’t use third-person language like user or customer in public-facing materials written for those very same users and customers—address them directly instead!
Singular they
When referring to a person of indeterminate or unknown gender, use the singular they rather than gendered pronouns like she, he, or any combination thereof (like (s)he or his or her).
-
No: Someone left his or her bike outside.
-
Yes: Someone left their bike outside.
Pronouns and clarity
Make sure that each pronoun has a clear antecedent. (In other words, make sure it’s obvious what the pronoun is referring to.) One of the easiest ways to avoid ambiguity is to repeat the actual noun instead of using a pronoun in its place.
-
Unclear: The boy hit the bat against the pillar until it broke.
(What broke—the pole, or the pillar? There’s no way to tell from context alone.) -
Clear: The boy hit the bat against the pillar until the pillar broke.
(It was the pillar!)
Referring to groups of people
Always use who (instead of that) when referring to people, even if the group of people is abstract.
-
No: Send an email to users that registered early.
-
Yes: Send an email to users who registered early.
Spelling
American English
Use standard American English spelling conventions.
Verbs and tense
Present tense
Use the present tense whenever possible.
Future tense
However, it can sometimes be helpful to use the future tense for specific examples of cause and effect.
- Example: If you run multiple reports, each report will generate its own file.
API reference
In API reference documentation (and certain types of non-API glossaries), describe each item or method in the present continual tense rather than as an imperative or procedural instruction. In other words, describe what the method does, not what the user must do.
-
Weak:
end(): Cancel the current session.
(Implied subject is you—the user will cancel the session.) -
Strong:
end(): Cancels the current session.
(The subject is the method itself—the method cancels the session.)
However, if you’re describing how to use a method rather than a definition of what the method does, it’s okay to use standard procedural instructions.
- Example: Call
end()to cancel the current session.
For more information, see APIs and SDKs and Procedural Instructions.
Miscellaneous
Contractions
It’s okay to use contractions.
Data is singular
Treat data as a singular, uncountable noun.
-
No: The data support this conclusion.
-
Yes: The data supports this conclusion.
Phrasal nouns vs. phrasal verbs
Don’t use phrasal nouns and phrasal verbs interchangably. Although login and log in may look similar, they mean different things—a login (noun) is the credential you use to log in (verb).