Formatting text in instructions

Consistent text formatting helps readers locate and interpret information. Follow these conventions for formatting elements that frequently appear in instructions (also referred to as procedures).

See also
Describing interactions with UI
Capitalization
Formatting common text elements
Formatting developer text elements

In documentation and technical content

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

Element Convention Example
Blades Avoid talking about blades. Instead, describe what the customer needs to do.
When you must refer to a blade by name, use bold formatting for the name of the blade.
Use sentence-style capitalization unless you need to match the UI.
Don't include the word blade unless it adds needed clarity.
Select a specific operation to view details about that operation.
In Web app, provide a name for your site.
Go to Audit logs to view the events that occurred against the subscription.
On the Resource group blade, select Summary.
Buttons, checkboxes, and other options Avoid talking about UI elements. Instead, describe what the customer needs to do.
When you must refer to a button, checkbox, or other option, use bold formatting for the name.
Use sentence-style capitalization unless you need to match the UI. If an option label ends with a colon or an ellipsis, don't include that end punctuation in instructions.
Don't include the type of UI element, such as button or checkbox, unless including it adds needed clarity.
Select Save as (not Select Save as… or Select the Save as button).
Select Allow row to break across pages.
Clear the Match case checkbox.
Command-line commands Bold. All lowercase. copy
Command-line options (also known as switches or flags) Bold. Capitalize the way the option must be typed. /a
/Aw
Commands Use 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 names Bold. The capitalization of database names varies. WingtipToys database
Device and port names All uppercase. USB
Dialog boxes In general, avoid talking about UI. Instead, talk about what the customer needs to do.
When you need to refer to the UI element, use dialog. Don't use pop-up window, dialog box, or dialogue box.
When you must refer to a dialog by name, use bold formatting for its name.
Use sentence-style capitalization unless you need to match the UI. If a dialog label ends with a colon or an ellipsis, don't include that end punctuation in instructions.
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, clear the Shapes checkbox.
Error messages Sentence-style capitalization. Enclose error messages in quotation marks when referring to them in text. 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 attributes All lowercase. To remove the hidden attribute from all files in a folder ....
File name extensions All 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 sequences Capitalize. 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.
Macros Usually 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 variables Italic. a2 + b2 = c2
Menus Avoid 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 terms Italicize 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.
Palettes Avoid 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.
Panes Avoid 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 trademarks Usually 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
Slashes When instructing customers to enter a slash, include the spelled-out term (backslash or slash), followed by the symbol in parentheses. Enter two backslashes (\\) ....
Strings When 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.
Tabs Avoid 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, ….
Toggles Avoid 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.
URLs All 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 input Usually 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
Windows Avoid 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 elements Bold. Capitalization varies. ElementType element
xml:space attribute

In the UI and general content

Instructions can also appear in the UI itself and in content other than documentation, such as blogs and marketing. In this content, avoid bold and italic formatting. The goal is to be readable and friendly but also clearly set off the UI label or other text element from the surrounding text.

Choose one of the approaches below and use it consistently.

Option Example
Describe the action without referring to a specific UI label. Choose the group or groups that you want to assign services to.
Use wording that clearly sets off the name of the element. Assign services to the Business data only group.
By selecting the Create my database button, you agree Microsoft can use entity and field names you create to help improve our common data model.
Choose how often you want to refresh data in Schedule refresh.
Use quotation marks. Quotation marks can make text cluttered, so use them sparingly and only when necessary for clarity. Assign services to the “No business data allowed” group.
Use bold formatting. Assign services to either the Business data only or No business data allowed group.