Language
Communication is the way in which we share ideas and language is a tool we use to communicate. Transmitting the right message to your audience is key toward providing a encouraging experience for the user.
Abbreviations
Ensure that abbreviations aren't tailored to a specific audience unless the abbreviation has been well-defined prior to use within context of the message. For example, abbreviating new technologies should first be defined before use. Abbreviations with measurement units can be used with an assumption that they exist as common knowledge.
Jargon
When using unfamiliar words or concepts, put the word in quotations and then define the word soon after in a following sentence. Otherwise, attempt to avoid technical language unless it is directed at a specific audience. Aim to be clear with the message by using common language where possible. Consider simplifying or providing analogies.
Lists
When providing guidance by categorizing items together, consider using a list. Use a numbered list if the order of the items is important, otherwise a list using a symbol marking the item from body text is appropriate. Use a leading sentence to describe what is expected within the list. Do not indent the list more than twice; consider creating a separate list with leading text instead. Attempt to craft each item similarly to the others.
Files, folders, and urls
When referencing a file by name, ensure it matches exactly to how it would be found within the operating system. Include the file extension or describe the type of file by the application expected to open it. If expecting a user to traverse a system, be clear in technical commands. Do not assume the user knows what any one command means. Offer both graphical user interface guidance as well as command-line interface commands when possible, depending on the audience.
When providing a url, do not include the protocol (https://
) or subdomain (www
) unless the resource is inaccessible without it. If the url can be shortened, consider this for better accessibility where the url may not be interactive; when printed for example.
Nouns
Proper nouns are captialized in writing styles which include the differentiation of glyphs. Unless the style of the text is altered to signify a different context. In this design system, large headings have no capitalization while smaller headings, actions, labels are all uppercase.
Punctuation
Use proper punctuation in bodies of text, using proper localized methods. Headings, labels, and actions. Helping and error text for form inputs are also punctuated.