Language & grammar
dHighly recommended: Following the guidelines for language and grammar is encouraged as it will improve the user experience.
Use American English. No extra U’s or L’s!
Exception: We spell “catalogue” in a British way. Don’t ask why.
Use active voice over passive voice. The beginning of a sentence should start with the focus on the person or thing taking action (subject), and the action itself (verb). More details about the thing being acted upon (object) come later in the sentence. Cut away extra words that aren’t required and don’t directly relate to the goal of the sentence.
Formula: Subject (person or thing taking action) + verb + more information. Example: Verb: “Cut away” Object: “Words that aren’t required....” *Avoid starting sentences with “you can...” Start with instructive verbs instead. By giving an instruction, “you can” is assumed information.
Do: Press F5 on your keyboard to refresh your drawing.
Don't: To refresh your drawing, press F5.
Don't: You can refresh your drawing by pressing F5.
Use 2nd person (“you”) when interacting with the user. This includes in messaging seen in dialogs as well as the user's customized preferenences.
Do: Your preferences
Do: Your view modes
Don't: Custom preferences
Don't: User-created view modes
Use the name of the program, “the program,” or “it” when talking about the program being used.
When talking about another unidentified person, it is best to avoid gendered pronouns when possible. When it is necessary, use plural third person pronouns: they/their/them/theirs.
Do: Someone else has locked this section. Contact them to request permission to edit.
Do: Someone else has locked this section. Contact him or her to request permission.
Don’t: Someone else has locked this section. Contact him or her to request permission.
Examples from Atlassian's design system
Best: Ask your admin to add you OK: Ask your admin if they can add you. No: Ask your admin is he or she can add you.
