Formatting

Table of Contents

Refer here for all things related to formatting text and UI elements.

UI element conventions

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.

Don’t include/write the type of UI element, such as button or checkbox, unless including it adds needed clarity. Focus more on describing how the user needs to interact with the UI than describing the UI elements themselves. Clarity is subjective, so use your best judgment or consult with the technical editor.

ElementConventionExamples
Buttons, checkboxes, and other optionsWhen possible, avoid talking about UI elements.

Instead, describe what the customer needs to do.

If an option label ends with a colon or an ellipsis, don’t include that end punctuation in instructions.

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, not quotation marks, to refer to or set apart words or parts of sentences, such as typing/text inputs or newly introduced terms.

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.

Blockquotes

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.

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 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 and not alerts, warning messages, message boxes, or prompts.
  • Warning message is acceptable to use in content for a technical audience to describe messages that indicate an error condition. It is also acceptable to use if you must follow the user interface. However, don’t 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.
Format punctuation in UI interactions

Use the following rules regarding punctuation formatting in text describing interaction with the UI, periods, parentheses, and brackets.

  • If the punctuation is part of the element, such as punctuation that the customer must type, format the punctuation the same as the element.

Examples:

Type Balance due: in cell A14. (In this example, the colon is bolded because the user types the colon.)

Navigate to Settings, then select Allow creation of contacts with duplicate SSNs. (The period is bolded because it is part of the UI element.)

  • If the punctuation isn’t part of the element, format the punctuation the same as the main text. This includes the > bracket when delineating a sequence of screens or menus.

Example:

On the Insert menu, go to Pictures, and then select From File. (In this example, the comma following Pictures and the period following File aren’t bold because the punctuation isn’t part of the UI labels.)

  • Format parentheses and brackets in the font style of the main text, not of the text in the parentheses or brackets.
    •  Exceptions: For notes, tips, warnings, figure notations, and table notations, bold both the word/caption title and the colon that follows.

Parentheses and brackets

Format parentheses and brackets in the font style of the main text, not of the text in the parentheses or brackets.
Example:
Open any Office app and select File > Account. (If you’re doing this in Outlook, select File > Office Account.)
(In this example, the opening and closing parentheses aren’t bold, to match the main text.)

Use the same font style for the closing parenthesis or bracket that you use for the opening parenthesis or bracket.

How to format less common UI elements

In documentation and technical content

Use these conventions in instructions that appear in documentation and technical content.

ElementConventionExample
Command-line commandsBold. All lowercase.copy
Command-line options (also known as switches or flags)Bold. Capitalize the way the option must be typed./a
/Aw
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.
Don’t include the word command unless it adds needed clarity.
Go to Tools, and select Change language.

On the Design menu, select Colors, and then select a color scheme.
Database namesBold. The capitalization of database names varies.WingtipToys database
Device and port namesAll uppercase.USB
Error messagesSentence-style capitalization. Enclose error messages in quotation marks when referring to them in text.We can’t find a scanner.
Hmm … looks like that’s a broken link.

If you see the error message, “Check scanner status and try again,” use Windows Update to check for the latest drivers for your device.
File attributesAll lowercase.To remove the hidden attribute from all files in a folder ….
File name extensionsAll lowercase..mdb
.doc
File names (user-defined examples)Title-style capitalization. It’s OK to use internal capital letters in file names for readability. Use bold formatting for file names in procedures if you’re directing the customer to select, type, or otherwise interact with the name.My Taxes for 2016

MyTaxesFor2016

Enter MyTaxesFor2016.
Folder and directory names (user-defined examples)Sentence-style capitalization. It’s OK to use internal capital letters in folder and directory names for readability. In procedures, use bold formatting for names if you’re directing the customer to select, type, or otherwise interact with the name.Vacation and Sick Pay
MyFiles\Accounting\Payroll\VacPay
Select Documents.
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.
To learn how to refer to keyboard shortcuts and specific keys, see Keys and keyboard shortcuts term collection.
Shift, F7
Ctrl+Alt+Del
Alt, F, O
Spacebar
Select the F1 key.
To open the Preview tab, select Alt+3.
MacrosUsually all uppercase. Use bold formatting if predefined. Might be monospace if user defined. Treatment varies.LOWORD
MASKROP
Markup language elements (tags)Bold. Capitalization varies.<img>
<input type=text>
<!DOCTYPE html>
Mathematical constants and variablesItalic.a2 + b2 = c2
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.
New termsItalicize the first mention of a new term if you’re going to define it immediately in text.Microsoft Exchange consists of both server and client components.
PalettesAvoid talking about palettes. Instead, describe what the customer needs to do.
When you must refer to a palette by name, use bold formatting for the name of the palette.
Use sentence-style capitalization unless you need to match the UI.
Don’t include the word palette unless it adds needed clarity.
In Colors, let Windows pull an accent color from your background, or choose your own color.
In the Color palette, select a color for the object outline.
PanesAvoid talking about panes. Instead, describe what the customer needs to do.
When you must refer to a pane by name, use bold formatting for the name of the pane.
Use sentence-style capitalization unless you need to match the UI.
Don’t include the word pane unless it adds needed clarity.
Select the arrow next to the Styles gallery, select Apply styles, and then select a style to modify.
If the Apply Styles pane is in your way, just move it.
Placeholders (in syntax and in user input)Italic./v: version
Enter password.
Products, services, apps, and trademarksUsually title-style capitalization. Check the Microsoft trademark list for capitalization of trademarked names.Microsoft Arc Touch Mouse
Microsoft Word
Surface Pro
Notepad
Network Connections
Makefile
RC program
SlashesWhen instructing customers to enter a slash, include the spelled-out term (backslash or slash), followed by the symbol in parentheses.Enter two backslashes (\\) ….
StringsWhen referring to strings in code, a document, a website, or UI, use sentence-style capitalization unless the text you’re referring to is capitalized differently. Enclose in quotation marks.Select “Now is the time.”
Find “font-family:Segoe UI Semibold” in the code.
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, ….
TogglesAvoid talking about toggles. Instead, describe what the customer needs to do.
When you must refer to a toggle by name, use bold formatting for the name of the toggle.
Use sentence-style capitalization unless you need to match the UI.
Include the word toggle if it adds needed clarity.
To make text and apps easier to see, turn on the toggle under Turn on high contrast.
To keep all applied filters, turn on the Pass all filters toggle.
URLsAll lowercase for complete URLs. If necessary, line-break long URLs before a slash. Don’t hyphenate.
See also URLs and web addresses.
www.microsoft.com
msdn.microsoft.com/downloads
User inputUsually lowercase, unless case sensitive. Bold or italic, depending on the element. If the user input string contains placeholder text, use italic for that text.Enter hello world
Enter -p password
WindowsAvoid talking about windows. Instead, focus on what the customer needs to do.
When you must refer to a window by name, use regular text. Use sentence-style capitalization unless you need to match the UI.
Use window only as a generic term for an area on a PC screen where apps and content appear. Don’t use window to refer to a specific dialog box, blade, or similar UI element.
To embed the new object, switch to the source document.
Easily switch between open windows.
Open a new Microsoft Edge tab in a new window so you can look at tabs side by side.
XML schema elementsBold. Capitalization varies.ElementType element
xml:space attribute
Non-UI bolding conventions

Release notes

All release notes indicate the release date at the beginning of the post. Use body text for this. Bold Release Date: and don’t bold the date.

Example:

Release Date: January 2021

Additional information

For more information on formatting text, see:

Table of Contents