Voice & Tone

Accessibility

It is important that users are able to successfully interact with our products, regardless of ability. When writing content, keep in mind that not all users will have the same kind of ability and that accessibility is a UX requirement, not a nice-to-have.

Guidelines

  • When writing, put yourself in the user's position
    • Ask yourself, would a regular, non-technical person who is not a superuser understand this?
    • If they wouldn't, are you giving them resources or information to help them understand?
  • When using an icon or visual element, always accompany it with a text alternative
    • The text alternative does not have to be visible to sighted users, invisible text can be used
    • Text is unnecessary if the visual element is non-essential
  • All tables require captions, even if captions are not visible to sighted users
  • All form controls require labels, even if labels are not visible to sighted users
  • Use unique and descriptive text for buttons and links
    • Instead of 'View Customer', say 'View John Doe'
    • Instead of 'Back', say 'Back to Search Results
  • Use consistent naming conventions across products and training materials
    • Avoid object name synonyms
      • For example, Content Block vs Content Map vs Content Snippet
  • Organize your text content in a scannable hierarchy
    • This can include different sized headers, subheaders, and lists
  • Always include alt text for visual elements unless the element is not essential to the user's overall experience
  • Avoid jargon, technical wording, or highly specialized language that will not be understood by a layperson
  • Avoid using directional language to refer to items within the page
    • Above / below etc. may mean something to sighted users, but not to users requiring screen readers or other assistive technology
  • Don't rely on visual elements to communicate to the user

Internationalization

Internationalization refers to the translating of text into other languages. We can help to make this process easier by adhering to certain guidelines.

Guidelines

  • Use the active voice and positive language
  • Use consistent date and time formats
  • Use consistent naming across products and training materials
  • Avoid unnecessary abbreviations
  • Avoid slang, idioms, and jargon
  • Avoid double negatives
  • Avoid unclear pronouns
    • An unclear pronoun happens when a pronoun (usually 'it', 'this', 'that', or 'they') could refer to more than one antecedent within the sentence.
      • For example, the teacher gave the student her notes.
        • Who do the notes belong to? The teacher or the student?