Formatting

Table of Contents

Bold formatting

When referring to any UI element by name, put its name in boldface. This includes names for buttons, menus, dialogs, windows, list items, or any other feature in the UI that has a visible name. Use appropriate nouns and verbs to describe how to interact with them—it is important to focus on the task, not only how the user interacts with the UI element. However, know the audience and understand the context. There are many cases where the point of documentation is to guide readers through elements on a page.

UI bolding rules

ElementConventionExamples
Buttons, checkboxes, and other optionsAvoid talking about UI elements. Instead, describe what the customer needs to do.

When you must refer to a button, check box, or other option, use bold formatting for the name.

Select Save as (not Select Save as… or Select the Save as button).

Select Allow row to break across pages.

Clear the Match case check box.

CommandsUse bold formatting for command names.

Use sentence-style capitalization unless you need to match the UI. If a command label ends with a colon or an ellipsis, don’t include that end punctuation in instructions.

Go to Tools, and select Change language.

On the Design menu, select Colors, and then select a color scheme.

Dialog boxesAvoid talking about dialog boxes. Instead, describe what the customer needs to do. When you must refer to a dialog box by name, use bold formatting for the name of the dialog box.

Use sentence-style capitalization unless you need to match the UI. If a dialog box label ends with a colon or an ellipsis, don’t include that end punctuation in instructions.

Don’t include the words dialog box unless it adds needed clarity.

Select Upload, and then select a file to upload.

In Properties, select Details, and then select Remove Properties and Personal Information.

In the Protect document dialog box, clear the Shapes check box.

Key names, combinations, and sequencesCapitalize. Use bold formatting for key names and keyboard shortcuts in instructions. Don’t put a space around the plus sign (+) in keyboard shortcuts.Select the F1 key.

To open the Preview tab, select Alt+3.

MenusAvoid talking about menus. Instead, describe what the customer needs to do.

When you must refer to a menu by name, use bold formatting for the name of the menu.

Use sentence-style capitalization unless you need to match the UI.

Don’t include the word menu unless it adds needed clarity.

Go to Tools, and select Change language.

On the Design menu, select Colors, and then select a color scheme.

TabsAvoid talking about tabs. Instead, describe what the customer needs to do.

When you must refer to a tab by name, use bold formatting for the name of the tab.

Use sentence-style capitalization unless you need to match the UI.

Don’t include the word tab unless it adds needed clarity.

Select the table, and then select Design > Header row.

On the Design tab, select Header row.

Go to the Deploy tab. In the Configuration list, ….

Feature namesDon’t make an official feature name or product name bold, except when it directly refers to an element in the page that uses the name (such as a window title or button name).BriteAuth is a centralized user identity management service that supports single sign-on (SSO) for your entire suite of internal and external apps.

There are six broad steps to onboarding new providers on BriteApps.

Italics

Use italics if you need to refer to or set apart words or parts of sentences.

Examples:

Incorrect: “Info” is not an acceptable abbreviation for “information” in professional communications.

Correct: Info is not an acceptable abbreviation for information in professional communications.

Additional Information

For more information on formatting text, see:

Table of Contents