Grammar
Table of contents
Guidelines for building the grammatical machinery of a sentence.
Abbreviations
Latin abbreviations
It’s okay to use Latin abbreviations inside parentheses (e.g., like this), but not in the body of a sentence.
-
No: The beach is home to fish, crabs, sharks, etc.
-
Yes: The beach is home to fish, crabs, and so on.
-
Also yes: Many sea creatures (fish, crabs, sharks, etc.) live at the beach.
-
Also also yes: Many sea creatures (e.g., the loggerhead turtle) are endangered.
Don’t confuse i.e. (id est, that is to say) and e.g. (exempli gratia, for the sake of example). When in doubt, spell it out—use the English phrase instead!
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.
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!)
Similarly, when using relative pronouns like this or that, you can reduce ambiguity by also restating the word or concept you’re referring to (or replacing the pronoun entirely).
-
Unclear: Send all data to Aperture Science’s secure servers via carrier pigeon. This prevents hackers from intercepting your data.
(Which part thwarts hackers: sending data to Aperture Science’s secure servers, or the fact your data was sent via carrier pigeon?) -
Clear: Send all data to Aperture Science’s secure servers via carrier pigeon. This pigeon relay prevents hackers from intercepting your data.
(The pigeons thwart hackers!)
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.
Relative pronouns
The relative pronouns that and which are not interchangable—use that for restrictive clauses and which for nonrestrictive clauses. (A good rule of thumb: nonrestrictive clauses tend to be offset by commas, while restrictive clauses do not.)
-
Restrictive: The new bass that I bought last week has two humbucker pickups.
-
Nonrestrictive: The new bass, which I bought last week, has two humbucker pickups.
Sentence structure
And and but
It’s okay to start a sentence with and or but.
Conditional clauses
When applicable, put conditional clauses at the beginning of a sentence.
End prepositions
It’s okay to end a sentence with a preposition. However, if rewriting the sentence to avoid using an end preposition would help make its meaning clearer, you should try to rewrite it.
Spelling
American English
Use standard American English spelling conventions.
However, there may be exceptions to this rule when addressing audiences who are accustomed to another form of English—for example, if you’re writing a sales deck for a European audience, it may be more appropriate to use British English.
Verbs and tense
Present tense
Use the present tense whenever possible.
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).