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 optionsWhen possible, avoid 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 when possible. 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.Press 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 then select Change language.

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

TabsAvoid talking about tabs when possible. 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.

Report namesDon’t bold report names, except when the exact name appears in the UI and you are referring to it directly (this seems to not often be the case the way we write about the reports). Don’t capitalize the word report, unless it appears in the UI.Bold: Under Agency, select Agency Experience Paid Premium.

Don’t bold: The Agency Experience Paid Premium report is similar to the Agency Experience report, with a few differences.

Italics

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

Examples

Incorrect: “Info” isn’t an acceptable abbreviation for “information” in professional communications.

Correct: Info isn’t an acceptable abbreviation for information in professional communications.

Use italics to set apart any text you’re directing the user to type:

In the Search for a Setting box, type add-catastrophe-from-fnol.

Blockquote

WordPress’s Blockquote formatting provides an extra level of emphasis on important text and is required for tips, warnings, important notices, exceptions, etc. When these appear in documentation, the intent is to call out something to a reader’s attention so it stands out from the instructions.

Always bold the lead-in and the colon that follows it. Standard formatting rules apply for the content within the Blockquote item.

Note: Blockquote formatting always applies italics, which you can’t remove.

You can also use Blockquote formatting to set apart blocks of text, such as sample deliverable text, short blocks of code input, etc. Blockquote isn’t required for example/sample text.

Examples

Notes

A note indicates neutral or positive information that emphasizes or supplements important points in the main text.

Note: Any changes made to the Overridden entity in the parent product will be available in the current product.

Tips

A tip is a type of note that helps users apply the techniques and procedures described in the text to their specific needs.

Tip: You can set up an alert so designated agents receive an email notification each time someone submits a claim.

Important

An important note provides information that is essential to the completion of a task. Users can disregard important information in a note and still complete a task, but they shouldn’t disregard an important note.

Important: You must be logged in as an Administrator to complete this procedure.

Caution/Warning

A caution or warning is a type of note that advises users that failure to take or avoid a specific action could result in a global change or loss of data or other serious, adverse consequence.

Caution: To avoid damaging files, always shut down your computer before you turn it off.

Warning

A warning message is a modal dialog box, in-place message, notification, or balloon that alerts the user of a condition that might cause a problem in the future.

When referring to warnings, follow these guidelines:

  • In content for a general audience, refer to warnings as messages, not alerts, warning messages, message boxes, or prompts.
  • Warning message is all right to use in content for a technical audience to describe messages that indicate an error condition. It is also all right to use if you must follow the user interface. However, do not use warning without the word message.
  • Refer to the warning message by its main instruction, which may be a question. Use the exact text, including its capitalization. If the text is long or detailed, summarize it.

Sample text or code

This replaces all previously issued policy Declarations, if any. This policy only applies to those coverages for which a limit of liability is shown and a premium charge is made. This limit of liability for each coverage shall not exceed the amount stated for such coverage, subject to all the terms of this policy.

The policy Deductible reflected on this Declarations applies to all property coverages unless otherwise stipulated within the policy language.

Billing Schedule – {billing_schedule}

{print_description}

Excerpts

In WordPress excerpts, use the <strong> (or <b>) and <em> tags to bold and italicize text, respectively. The same rules for applying bold and italics that apply to all documentation apply to excerpts.

Example

Figure 1: Typed excerpt with bold formatting applied via HTML.
Figure 2: Excerpt displaying appropriately formatted text.

Additional information

For more information on formatting text, see:

Table of Contents