This standard covers how to compose user-focused text.
Style and Tone
- Be concise
Remove unnecessary words--too much text discourages users, who want to remain on task.
Original: Name should not be empty or consist only of white space.
Rewrite: Enter a user name.
Give users the information they need to resolve issues.
Original: Invalid tolerance value.
Rewrite: The tolerance value cannot be greater than 100.
Address the user as "you"
Ensure that your text is user-focused.
Example: You have chosen to shutdown host 10.112.2.165.
State instructions in the correct sequence
Tell users where in the UI to perform the action, and then tell them the action to perform.
Original: Select Removable Devices from the VM menu.
Example: On the VM menu, select Removable Devices.
Use active voice
Active voice makes writing more simple and direct.
Original: Selection of a host is required.
Rewrite: Select a host.
Avoid noun phrases and stacking modifiers before a noun
Readability suffers when nouns that are normally separate are grouped together or when multiple modifiers are used to describe a noun.
Original: Controls the network traffic filters configuration.
Rewrite: Controls the configuration of rules for network traffic filtering.
Avoid future tense
Describe the application's response to user input in present tense.
Original: Will replace the existing controller with new selected controller.
Rewrite: Replaces the existing controller with the selected controller.
Do not use contractions
Contractions pose a problem for translators and for people who are not native English speakers.
Original: Can't connect to vSphere Web Client
Rewrite: Cannot connect to vSphere Web Client
Use an article before a noun
Use "the" before singular and plural nouns when the noun is specific or particular. "The" signals that the noun is definite, and that it refers to a particular member of a group. Use "a" and "an" to modify nonspecific or non-particular nouns.
Original: Cannot reboot host.
Rewrite: Cannot reboot the host.
In this example, the author refers to a particular host, so the definite article is used.
- Use American spelling
- Words end in -ize (customize, organize)
- Words end in -yze (analyze)
- Words end in -og (analog, catalog, dialog)
- Words that end in unstressed -our in British English, end in -or (color, behavior)
- Words end in -er (center, manouver)
- Use after labels for text boxes, drop-down menus, sliders, text, and values.
- Use after a group label for a radio button or check box
- Use to introduce a group of items. For example: The following new features are available: Management Network Rollback and Recovery, Health Check, and LACP.
- Don't use after labels in a stack view.
- Use before the "and" or "or" in a series of three or more items. For example: The NTP Service settings are updated when you click Start, Restart, or Stop.
- Quotation Marks
- Use around a value only when it is necessary to prevent confusion from the rest of the text. For example: The "my_config" file is cloned and renamed to "my cloned config."
- Don't use around an object name that turns into a link, such as when the object name appears in a list.
- Don't use to distinguish button names. Capitalize the label instead. For example: Click Approve if you trust this product.
- Use If the text is a complete sentence.
- Don't use for sentence fragments.
- Use for truncated text, tasks that are in progress (for example, "Loading..."), and actions that open an input dialog or wizard.
- Don't use:
- For actions that open an informational dialog.
- In links, except when the matches an item in a menu that includes ellipsis.
- When referring to a button name in text.
- At the end of a sentence.
Abbreviations and Acronyms
- Show the full name whenever possible.
- If space is limited, use the acronym only if the abbreviated form is as familiar to your users as the full word or phrase. For example, VM is a familiar abbreviation for "virtual machine."
- Don't mix the full name and the acronym in the same sentence.
- Don't abbreviate product or feature names without approval from your legal and marketing representatives and the product manager.
- Use bold font, not italics, to emphasize specific words.
- Use bold sparingly—too much bold competes with title text, which is always bold.
Original: The VM storage policy matches datastores that satisfy any of the rule sets.
Rewrite: The VM storage policy matches datastores that satisfy any of the rule sets.
- Use an ellipsis to indicate text that is too long to fit in the available space, for example, a text string in a datagrid cell.
- Insert the ellipsis when the first character is truncated, at the end of the text. Don't truncate in the middle of the text string.
- Provide a tooltip that includes the complete text.
- If users are likely to copy read-only text, consider making it selectable. For example, users might copy the text in an error message or a URL.
Localization is the process of adapting an application for a particular region or language. Localization involves the translation of text and changes in word order, date and time formats, text direction, and so on. Therefore, plan for a 30 percent expansion of English text, at minimum, when writing text for your UI. In addition, consider using controls that can adapt to text that is significantly larger (that is, wraps to multiple lines instead of truncating the text on a single line).
Maintaining a consistent text hierarchy in an interface is key to maintaining a clear layout. Try to maintain left-alignment for most text and controls. Use your judgment, adjust padding and margins to improve text alignment and flow. Pay attention to horizontal spacing to maintain legibility.
In general, use #333333 type for content text and Interface headers.
Note that although Gotham Rounded is used as a brand indicator, it can not be used within an application's text areas. As indicated below, use the Arial typeface.