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. |