Skip to content

Formatting text

Jump to bottom
Luise Freese edited this page Jul 25, 2022 · 3 revisions

Consistent text formatting helps readers locate and interpret information. Follow these conventions for formatting elements in your posts.

Capitalization

Use sentence-style capitalization. That means everything is lowercase except the first word and proper nouns, which include the names of brands, products, and services.

Follow these guidelines:

  • Use sentence-style capitalization most of the time. That means:

    • Capitalize the first word of a sentence, heading, title, UI label (such as the name of a button or checkbox), or standalone phrase.
    • Capitalize proper nouns.
    • Use lowercase for everything else.

  • Always capitalize the first word of a new sentence. Rewrite sentences that start with a word that's always lowercase.

  • Don't use all uppercase for emphasis. (It's OK to use italic sparingly for emphasis.)

  • Don't use all lowercase as a design choice. Although all uppercase is used occasionally as a design element, don't use it in text.

  • Don't use internal capitalization (such as AutoScale or e-Book) unless it's part of a brand name.

  • Don't capitalize the spelled-out form of an acronym unless it's a proper noun.

  • When words are joined by a slash, capitalize the word after the slash if the word before the slash is capitalized.

    Examples

    Country/Region

    Turn on the On/Off toggle.

Titles and headings

Use sentence-style capitalization in most titles and headings: capitalize the first word and lowercase the rest.

Exceptions: Proper nouns, including brand, product, and service names, are always capitalized. If a title or heading includes a colon, capitalize the first word after it.

Titles of blog posts use sentence-style capitalization.

Examples

  • Watch your favorite HD movies, TV shows, and more
  • 1 TB of cloud storage
  • Choose the Office version that's right for you
  • Available for Microsoft partners and commercial and public-sector customers
  • Can a search engine predict the World Cup winner?
  • Block party: Communities use Minecraft to create public spaces

Instructions

Blades

Avoid talking about blades. Instead, describe what the reader 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.

Examples

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

Examples

  • 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

Formatted as code (monospace) using the backtick (```). All lowercase, unless the syntax requires it.

For more than one command, use a command block.

Examples

yo @microsoft/sharepoint

npm install
gulp bundle --ship
gulp package-solution --ship

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.

Examples

  • Go to Tools, and select Change language.
  • On the Design menu, select Colors, and then select a color scheme.

Device and port names

All uppercase.

Examples

USB

Dialog boxes

Avoid talking about dialog boxes. Instead, describe what the reader 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 they add needed clarity.

Examples

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

Error messages

Sentence-style capitalization. Enclose error messages in quotation marks when referring to them in text.

Examples

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

Attributes

Monospace. All lowercase, unless required by syntax

Examples

  • To remove the hidden attribute from all files in a folder...
  • Make sure to set the alt attribute for all images...

File name extension

Monospace. All lowercase.

Make sure to include the ..

Examples

  • .ts
  • .css
  • Look for a .json file.

File names

Title-style capitalization. It's OK to use internal capital letters in file names for readability. Use code (monospace) formatting for file names in procedures if you're directing the reader to select, type, or otherwise interact with the name.

If describing existing file names, use the same capitalization as the actual file name.

Examples

  • Select MyWebPart.tsx
  • When prompted to enter a name, enter MyFirstWebPart
  • Open the .gitignore file...

Folder and directory names

Sentence-style capitalization. It's OK to use internal capital letters in folder and directory names for readability. In procedures, use code (monospace) formatting for names if you're directing the reader to select, type, or otherwise interact with the name

Examples

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

Examples

  • Shift, F7
  • Ctrl+Alt+Del
  • Alt, F, O
  • Spacebar
  • Select the F1 key.
  • To open the Preview tab, select Alt+3.

Markup language elements (tags)

Monospace. Capitalization varies.

Examples

  • <img>
  • <input type="text">
  • <!DOCTYPE html>

Menus

Avoid talking about menus. Instead, describe what the reader 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.

Examples

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

Examples

Microsoft Exchange consists of both server and client components.

Panes

Avoid talking about panes. Instead, describe what the reader 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.

Examples

  • 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

Examples

  • /v: version
  • Enter password.

Slashes

When instructing customers to enter a slash, include the spelled-out term (backslash or slash), followed by the symbol in parentheses.

Examples

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

When referring to code, use the monospace style.

Examples

  • Select "Now is the time."
  • Find "font-family:Segoe UI Semibold" in the code.

Toggles

Avoid talking about toggles. Instead, describe what the reader 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.

Use the terms turn on and clear to refer to checking and unchecking a toggle, respectively.

Examples

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

If referring to a URL you with the readers to visit and want to display the URL value in text, wrap it with < and >.

If referring to a fictitious URL value, format it as monospace.

When displaying a URL, don't include https:// unless it is surrounded by < and >. Include the protocol only if it's something other than HTTP, such as File Transfer Protocol (FTP).

The trailing slash at the end of a URL is optional. In most cases, leave it off. Never use a trailing slash in a URL that ends with a file name.

To refer to an entire website or top-level domain, such as Microsoft.com, omit http://www from the URL and capitalize only the first letter of the URL, even if the site name is capitalized differently.

Examples

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.

If instructing to write code, consider using monospace.

Examples

  • Enter hello world
  • Enter -p password

Windows

Avoid talking about windows. Instead, focus on what the reader 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.

Examples

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

This document is based on the Microsoft style guide

Clone this wiki locally