Grammar and mechanics
Follow these simple grammar rules to ensure that what you write is consistent with other text throughout our products. This will make everything easier for users to understand, and help them focus on the tasks they need to get done.
Best practices
General rules for good copy:
- If you can cut a word, without losing clarity, cut it.
- If a shorter word can be as effective as a longer one, choose the shorter one.
- Avoid jargon or technical terms when there’s an everyday equivalent that works.
- Lead your copy with a strong verb that encourages action.
- Try to always write in active voice. But, if the situation calls for some diplomacy or tact, passive voice might be a better fit.
- Make it scannable and easy to digest. Use short sentences and paragraphs, but not to the point that it reads as choppy. Break up long blocks of text with subheadings or bullet points.
Active and passive voice
Try to write in active voice. Using active voice creates an informal tone, and motivates the user to participate. But, if you don't know who is responsible for an action, passive voice might be the the best choice.
First and second person
Writing in second person (you, your) shifts the focus to the user. For most UI copy and help content using second person is the best option.
There will be some situations where first person (I, we, our) makes sense. Especially if you need to take responsibility for a software error or a broken link.
Pronouns
Use the inclusive “they”, “them” and “their” as a singular pronoun. Use “he/him/his” and “she/her/hers” only when you’re talking about a specific person whose gender and pronoun preference you know.
Abbreviations
In keeping with our informal and conversational tone, spell out abbreviations. Don't use the Latin abbreviations "i.e." and "e.g.". They are often used incorrectly, and can confuse the user.
Contractions
Don’t be afraid to use them. It helps with the human and friendly voice and tone we aspire to. Write like how you would say it in a conversation.
Lists
Only use lists if you have two or more items. You can use two types of lists: bulleted or numbered. Use bulleted lists when the order of items in the list doesn't matter, and numbered lists when the items in the list need to follow a specific sequence.
Bulleted list
Use a bulleted list for items that don't have a sequential order or priority.
Numbered list
Use a numbered list for items that have a sequential order or priority, such as step-by-step instructions.
Links
Make your links descriptive and contextual. Don’t say phrases like “click here” or "follow the link". Screen readers will tell the user what the component is. Writing "Click this link to view reports" will read as "Click this link to link view reports".