Grammar & Mechanics

Follow these simple grammar rules to make everything easier for users to understand, and help them focus on the tasks they need to get done

• Active and Passive Voice
• First and Second Person
• Pronouns
• Abbreviations
• Contractions
• Lists
  • Bulleted List
  • Numbered List
• Links

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.

Examples

Examples

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.

Examples

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.

Examples

Pronouns

Don't use gendered pronouns (like she/her, he/him). Follow these guidelines to write in an inclusive language:

• Use second person (you).
• Use the person's role (volunteer, donor, peer matcher).
• Use people, person or individual.
• You can use "they/them/their" as a singular pronoun in general references—like when talking about a group of volunteers.

If it's a real person, and you know their pronouns, use them!

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.

Examples

Examples

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.

Examples

Examples

Lists

Bulleted List

Use a bulleted list for items that don't have a sequential order or priority.

Here's a few special items that will elevate your regular morning coffee:

• Slow-roasted and organic coffee beans.
• Fancy coffee machine.
• Handmade wooden stir spoon.

Numbered List

Use a numbered list for items that have a sequential order or priority, such as step-by-step instructions.

To save your article on making coffee:

1. Go to File > Save as...
2. Enter a name for the file.
3. Select Save.

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 donate now" will read as "Click this link to link donate now".

Examples