Text craft

Explore how we shape language to convey meaning, perfect spelling and punctuation for readability, refine grammar for coherence, design intuitive UI elements for seamless interaction, and tailor localization for global accessibility.

Language

Capitalization

• Use sentence-style capitalization most of the time. That means capitalize the first word of a sentence, heading, title, UI label (including button names).

• Capitalize proper nouns.

• Use lowercase for everything else.

• When words are joined by a slash, capitalize the word after the slash, for example, Country/Region.

• Use all lowercase for file extensions.

Acronyms

• Use acronyms – if the first time you use this acronym introduce a definition, for example, RoPE (Role and Policy Engine).

• Use Omada Identity (instead of OI).

• Don’t introduce acronyms that are used just once.

• Avoid using acronyms in titles and headings.

• Add s to make an acronym plural – for example, APIs. –

• Avoid the possessive form – unless the acronym refers to a person or an organization (CEO’s).

Grammar and parts of speech

• Verbs: present tense.

• Person: second person (you, yours).

• Avoid passive voice. Use the active voice for improved clarity.

• Use bias-free communication, that is, don't use he, him, his, she, her, or hers in generic references. Instead:

  • Rewrite to use the second person (you).

  • Rewrite the sentence to have a plural noun and pronoun.

  • Use the or an instead of a pronoun (for example, "the document").

  • Refer to a person's role (reader, employee, customer, or client, for example).

  • Use person or individual.

  • Use singular they.

• Avoid using Latin abbreviations, use their English equivalents instead. Avoid e.g., etc.; instead, use for example, that is, and so on.

• Do not separate examples from a sentence, that is, embed examples in a sentence.

  • Correct: Refer to a person's role (reader, employee, customer, or client, for example).
  • Incorrect: Refer to a person's role. For example, reader, employee, customer, or client.

• Don't use contractions in technical communication.

• Omit unnecessary prepositions.

  • Correct: Click Cancel.

  • Incorrect: Click on Cancel button.

• Put conditional clauses before instructions, not after.

  • Correct: To delete the entire document, select Delete.

  • Incorrect: Select Delete if you want to delete the entire document.

Spelling and punctuation

Element	Usage
Colons	Within sentences: Use colons at the end of a statement followed by a second statement that expands on it. In Predicting list. In titles and headings: Capitalize the word that follows it Lowercase the word that follows it unless the colon introduces a direct quotation, the first word after the colon is a proper noun. In titles and headings. In UI: don’t use colon when introducing a lists of radio buttons or checkboxes.
Commas	Before the conjunction in a list (use serial comma). Following an introductory phrase. To join independent clauses with a conjunction, such as and, or, but, or so.
Em dash	Use: To set off a parenthetical phrase with more emphasis than parentheses provide. Don’t add spaces around an em dash. On each side of a phrase embedded in a sentence. To set off a phrase or clause at the end of a sentence. Don't use: In place of a bullet character in a list. To indicate an empty cell in a table. Don’t capitalize the first word after an em dash unless the word is a proper noun Example: The information in your spreadsheet—numbers, formulas, and text—is stored in cells.
En dash	To indicate a range of numbers, such as inclusive values, dates, or pages. To indicate negative numbers, for example, 2015–2017
Ellipses	Don’t use except indicating omitted text.
Hyphens	Hyphenate two or more words that precede and modify a noun as a unit if: Confusion might result without the hyphen. One of the words is a past or present participle (a verb form ending in -ed or -ing and used as an adjective or noun). The modifier is a number or single letter plus a noun or participle.
Periods	Don't use in: Headings Subheadings UI Titles UI Text Simple list (three or fewer words.)
Numbers	In body text spell out whole numbers from zero through nine and use numerals for 10 or greater.
Quotation marks	Use double quotation marks (" ") no single quotation marks (' ')

Date and formats

Date and format	Usage
24/7	Don't use. Use all day, every day, always, or something similar.
AM, PM	Use  AM  and  PM (preceded by a space). Use capital letters for  AM  and  PM.
Dates	Use the following format for dates: month day, year, as in July 31, 2016. Don't use day month year, as in 31 July 2016. In UI, it's OK to use numbers and slashes for dates if the code supports that format and automatically displays the appropriate date format for different locales. Don't use ordinal numbers (such as 1st, 12th, or 23rd) to indicate a date.
Days of the week: Sunday–Saturday	Capitalize the days of the week. Don't use abbreviations unless space is extremely limited. Don't include a period with the abbreviations. Three-letter abbreviations are preferred: Sun, Mon, Tue, Wed, Thu, Fri, and Sat In calendars and date picker UI controls, it's OK to use two-letter or one-letter abbreviations: Su, Mo, Tu, We, Th, Fr, and Sa S, M, T, W, T, F, and S.
Midnight, noon	Use noon and midnight. Don't use 12:00 noon and 12:00 midnight.
Months: January–December	Capitalize the names of months and their abbreviations. Don't use abbreviations unless space is extremely limited. Use three-letter abbreviations when necessary: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec Don't include a period with the abbreviations.
Time zones: Eastern Time, Central Time, Mountain Time, Pacific Time, Coordinated Universal Time (UTC), Greenwich Mean Time (GMT)	Capitalize time zones. Don't abbreviate unless space is severely limited. If you must abbreviate, use ET, CT, MT, and PT. Don't specify standard time or daylight saving time unless you're providing information about a specific event where that information matters. If you're referring to a time zone as a geographical area, call it a zone.

UI elements

Most of the time, avoid talking about UI elements. The table below lists some of the UI elements and associated verbs along with their usage rules and examples. If missing any, refer to the Microsoft Style Guide documentation.

UI element	Rule and example
Box	When you need to refer to dialog box elements by name, use box instead of field to refer to any box except a checkbox or a list box. For a checkbox, use the complete term, checkbox. For an element that displays a list, such as a dropdown list box, use list instead of box for clarity. Example - the File Name box
Checkbox	Use select and clear with checkboxes
Button	When you need to discuss UI elements, use button instead of command button, option button, or action button. If possible, refer to a button by its label only without using the word button. Example - Select a file, and then select OK.
Cancel	Use cancel the selection instead of deselect or unmark. Use clear to refer to checkboxes. Use cancel to describe ending code requests and processes before they're complete.
Click	Avoid this verb, which is specific to using a mouse. Instead, use verbs that work with multiple devices, such as select. It's OK to use click when you need to describe mouse actions specifically.
Close	Spell out and capitalize the word Close. It's OK to use the Close button to eliminate ambiguity in content that teaches beginning skills, but for general audiences, just use Close. Use bold for Close when you're talking about the Close button.
Cloud	Don't capitalize cloud except in references to the Microsoft Cloud or when it's part of a product name. Use cloud mostly as an adjective. Use sparingly as a noun—instead of the cloud, talk about cloud computing, cloud services, or a specific service or functionality and what the customer can do with it.
Deinstall	Don't use except to reference the term when it appears in the UI or an API. Don't use deinstall to refer to the related action. Use remove instead.
Delete	Use as a verb to describe the results of using the Delete or Cut command, such as moving files to the Recycle Bin in Windows, moving items to the Deleted folder in Outlook, and moving items to the clipboard. Use delete to describe these actions even if the customer uses a different method, such as by dragging a file to the Recycle Bin or using the Cut command. Use delete to refer to actions that result from pressing the Delete or Backspace key on the computer, such as deleting selected text.
Download	Use download to describe the intentional transfer of data and files to a system or device. Use install to describe adding apps, hardware, and drivers to a device.
Drag and drop	Don't use drag and drop except as an adjective to describe behavior that a programmer puts in a program, such as drag-and-drop editing or drag-and-drop feature. Use move or drag instead.
Exit	Don't use to describe closing an app or program.
Extension	Use instead of file extension. Examples: - the .bak extension - the .bak file name extension
Field	Don't use to refer to a text-entry box. Refer to the box by its label. If you must use a descriptor, use box instead of field.
File	Try to use a more specific term, such as document (Word), workbook (Excel), or presentation (PowerPoint).
File attributes	Use lowercase for file attributes such as hidden, system, read-only, and archive.
Finalize	Don't use. Use finish or complete instead.
Icon	Use only to describe a graphic representation of an object that a customer can select and open, such as a drive, folder, document, or app.
Info	It's OK to use info as an abbreviation for information in content with an informal tone. Global tip The abbreviated form isn't available in all languages, so allow enough space for the full translated term in localized content.
Navigate	Don't use to describe going from place to place on the internet or an intranet. Use browse instead. To describe going directly to a webpage or website, whether by entering a URL or selecting a link, use go to.
Select	Use select to refer to marking text, objects, cells, and other items that a customer will take action on, such as copying or moving. Describe the marked items as the selection or the selected text, objects, cells, and so on.
Sign in, sign out	Use sign in to describe starting a session on a computer, a device, a network, an app, or anywhere a username and password are required. Use sign out to refer to ending a session. Don't use log in, login, log into, log on, logon, log onto, log off, log out, logout, sign into, signin, signoff, sign off, or sign on unless these terms appear in the UI (and you're writing instructions).

Localization

UI element	Usage
Units of measure	Use numerals for measurement of distance, temperature, volume, size, weight, pixels, points, and son on – even if the number is less than 10. Insert a space between the unit measure and the numeral, or hyphenate if measurement modifies a noun. Use abbreviations only with numbers in specific measurements, such as 20 MP, and don't follow the abbreviation with a period. Use commas in numbers that have four or more digits, regardless of how the numbers appear in the UI: 1,093 MB For years, pixels, and baud use commas only when the number has five or more digits: 1920 × 1080 pixels, 10,240 × 4320 pixels, 9600 baud, 14,400 baud. Don’t use commas after the decimal point in decimal fractions. When the unit of measure is spelled out, use the singular form when the number is 1. Use the plural form for all other measurements.
Currency	In general, lowercase the names of currencies, but capitalize the reference to the country or region. Examples: US dollar
URLs	Don't include https:// in a URL. Include the protocol only if it's something other than HTTP, such as File Transfer Protocol (FTP).