Use this page for suggested common grammar rules and standards when writing technical documents. You can also check out Purdue Online Writing Lab or Chicago Manual of Style (subscription required) for complete grammar rules.
Active voice vs. passive voice
- Active makes your meaning clear for readers, keeps sentences from becoming too complicated, and almost always has a lower character and word count.
- Passive voice is a ‘to be’ verb followed by an action verb.
- Active voice example 1: Reset the TV every week.
- Passive voice example 1: The TV should be reset every week.
- Active voice example 2: The team is going to make an announcement tonight!
- Passive voice example 2: An announcement is going to be made by the team tonight!
Gender-specific & personal pronouns
- Avoid gender-specific pronouns ‘he, she, his, her, etc.’ When possible, use plural pronouns instead (their).
- Avoid using personal pronouns in content when possible. This allows you to be more direct to the reader.
- Use: If experiencing issues, turn off the router.
- Do not use: If experiencing issues, you can turn off the router OR If experiencing issues, the customer can turn off the router.
Noun & pronoun agreement
Ensure your nouns match your pronouns, such as plural nouns with a matching plural pronoun in your sentences.
- Use: Inform the user that they need to return the item.
- Use: Inform users that they need to return their item.
- Do not use: Inform the user that they need to return their item.
Point of view
- Always use second or third person point of view.
- Second person uses the pronoun ‘you. For example, ‘If you want to reset the device, press and hold the power button.’
- Third person uses pronouns like ‘they, their, or ‘the customer, or customers.’ For example, ‘The user must provide their current login information.’
- Remain consistent with your point of view in a document. Pick one and stick with it for consistency.
Subject & verb agreement
- When the subject of a sentence is composed of two or more nouns or pronouns connected by ‘and’, use a plural verb. For example, ‘The item and the rules are at the store.’
- When two or more singular nouns or pronouns are connected by ‘or’ or ‘nor’, use a singular verb. For example, ‘The screen or the button is on the front of the device.’
- When a compound subject contains both a singular and a plural noun or pronoun joined by ‘or’ or ‘nor’, the verb should agree with the part of the subject that is nearer the verb. For example, ‘The boy or his friends run every day. His friends or the boy runs every day.’
- While all verb tense (past, present, and future) is acceptable, present tense is the preferred tense for technical writing.
- Writing in present tense should, in most cases, reduce word count and make your content more concise.
- Present tense example: The router registers on the network upon startup.
- Past tense example: The router has registered on the network upon startup.
- Future tense example: The router will register on the network upon startup.