Skip to main content
Version: Omada Identity on-premises 16.0.1

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.

tip

This page summarizes the Microsoft Style Guide, which is our only source of truth. If you're in doubt, or if a case isn't covered here, check the Microsoft Style Guide and follow it.

Language​

Capitalization​

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

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

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

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

  • In titles and headings that include a colon, capitalize the first word after the colon.

  • Use all lowercase for file name extensions, for example, .md.

Acronyms​

  • Use only acronyms that your audience knows. Some acronyms, such as API, URL, and USB, are better known than the spelled-out term, so don't spell them out.

  • If you use an acronym that your audience might not know, spell out the term on first mention and add the acronym in parentheses, for example, Role and Policy Engine (RoPE). On later mentions on the same page, you can use the acronym alone.

  • Lowercase the spelled-out term unless it's a proper noun, for example, single sign-on (SSO).

  • Use Omada Identity (instead of OI). Don't create acronyms from product or feature names.

  • Don't introduce acronyms that are used just once. Spell out the term instead.

  • Avoid using an acronym for the first time in a title or heading, unless it's a keyword that you need for SEO. If you do, introduce the acronym in the body text that follows.

  • Use a or an depending on how you pronounce the acronym, for example, a URL, an API.

  • Add a lowercase 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, your).

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

    If you can't write around the problem, it's OK to use they, their, or them to refer to a single person. Don't use constructions like he/she or s/he.

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

  • Don't 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.
  • Contractions:

    • Write using the same, everyday words you use in conversation.
    • Use common contractions, such as it's, you're, that's, and don't, to create a friendly, informal tone.
    • Don't mix contractions and their spelled-out equivalents in UI text. For example, don't use can't and cannot in the same UI.
    • Never form a contraction from a noun and a verb, such as Omada's developing new features.
    • Avoid ambiguous or awkward contractions, such as there'd, it'll, and they'd.
    • For more information, check the Microsoft Style Guide.
  • Omit unnecessary prepositions.

    • Correct: Select Cancel.

    • Incorrect: Click on the 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​

ElementUsage
Colons
  • Before lists: You can use a colon at the end of a phrase that introduces a list, for example, a sentence that ends with "the following" or a fragment that the list items complete.
  • Within sentences: Avoid using a colon to introduce a clarification of the main statement. Rephrase the sentence, split it into two sentences, or use a comma or an em dash instead. If you do use a colon within a sentence, lowercase the word that follows it unless it's a proper noun or the first word of a direct quotation.
  • In titles and headings: Don't end a title or heading with a colon. You can use a colon within a title or heading to divide it into two parts. Capitalize the word that follows it.
  • Before images, tables, and code samples: Don't use a colon at the end of the phrase that introduces them. Use a period instead.
  • In UI: Don't use a colon at the end of headings, input labels, command names, or labels for buttons, checkboxes, and other options. If the UI label has a colon, don't include it when you refer to the element in documentation.
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 dashUse:
  • To signal a break in thought, or to set off a clarification or parenthetical remark within a sentence.
  • On each side of a phrase embedded in a sentence.
  • To set off a phrase or clause at the end of a sentence.
  • Example:
    The information in your spreadsheet—numbers, formulas, and text—is stored in cells.
Guidelines:
  • Don't add spaces around an em dash.
  • Don't capitalize the first word after an em dash unless the word is a proper noun.
  • Don't overuse em dashes, because they can make sentences long and hard to read.
  • Don't use multiple hyphens in place of an em dash.
En dash
  • To indicate a range of numbers or dates, for example, 2015–2017.
  • Instead of a hyphen in a compound modifier that includes an open compound, for example, Omada Identity–compatible systems.
  • Don't add spaces around an en dash, except in a time stamp in UI (2:15 PM – 4:45 PM) or in a range that includes both times and dates.
  • Don't use an en dash in place of the minus sign.
Minus sign
  • Use the minus sign (−) for negative numbers and subtraction, for example, −12.
  • For accessibility, don't use an en dash or a hyphen instead of the minus sign.
Ellipses
  • Don't use except indicating omitted text.
HyphensHyphenate two or more words that precede and modify a noun as a unit if:
  • Confusion might result without the hyphen, for example, built-in drive.
  • 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), for example, left-aligned text.
  • The modifier is a number or single letter plus a noun or participle, for example, two-sided arrow.
Don't hyphenate:
  • Very or an adverb ending in -ly when it precedes another modifier, for example, highly graphical interface.
  • A predicate adjective (an adjective that follows a linking verb), for example, The text is left aligned.
  • Most prefixes, such as non-, pre-, re-, and sub-, for example, subfolder.
Periods
  • End all sentences with a period, even if they're only two words.
  • Put one space, not two, after a period.
Don't use in:
  • Headings
  • Subheadings
  • UI titles
  • UI text
  • Simple lists (three or fewer words per item)
In lists:
  • If one or more list items complete the phrase that introduces the list, or are complete sentences, end every item with a period.
Numbers
  • In body text spell out whole numbers from zero through nine and use numerals for 10 or greater.
Quotation marks
  • Use straight double quotation marks (" "), not single quotation marks (' ').
  • Use single quotation marks only for a quotation inside a quotation.
  • Place closing quotation marks outside commas and periods, and inside other punctuation, unless the punctuation is part of the quoted material.

Date and formats​

Date and formatUsage
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. Instead, describe what the user needs to do. Users interact with the product by using a keyboard, mouse, touch, or voice, so use generic verbs that work with any input method, such as select. Don't use input-specific verbs, such as click or swipe.

The table below lists some of the UI elements and associated verbs along with their usage rules and examples. If an element or verb is missing, refer to the Microsoft Style Guide documentation.

UI elementRule and example
>
  • Use to separate steps in a UI path when the path is clear and the selection method is the same for each step.
  • Include a space before and after the symbol, and don't make it bold.
  • Example - Select Setup > Systems.
Box
  • When you need to refer to elements in a dialog 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
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.
Checkbox
  • Use select and clear with checkboxes.
  • Example - Clear the Match case checkbox.
Choose
  • Use for choosing an option based on the user's preference or desired outcome.
  • Use to avoid a repeated word when the option starts with Select.
  • Example - Choose Select users.
Click
  • Don't use this verb, which is specific to using a mouse. Instead, use verbs that work with all input methods, such as select.
Close
  • Use for apps, panes, dialogs, files, notifications, and tabs.
  • 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 unless 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 permanently removing an item, such as an object, a file, or selected text.
  • Use delete to describe these actions even if the user uses a different method, such as a keyboard key or a command.
Dialog
  • Use dialog, not dialog box, pop-up window, or dialogue box.
  • When you must refer to a dialog by name, use bold for its name.
  • Example - In the Protect document dialog, clear the Shapes checkbox.
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.
Enter
  • Use to instruct the user to type or otherwise insert a value.
  • Example - In the Name box, enter a name for the system.
Exit
  • Don't use to describe closing an app or program. Use close instead.
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.
  • It's OK to use field in a database context and other technical contexts, for example, the fields of a data object type.
File
  • Try to use a more specific term, such as report, configuration file, or log file.
File attributes
  • Use lowercase for file attributes such as hidden, system, read-only, and archive.
Finalize
  • Don't use. Use finish or complete instead.
Go to
  • Use for going to a tab, a menu, or another place in the UI, and for going to a website or webpage.
  • Example - Go to the Settings tab.
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.
  • The abbreviated form isn't available in all languages, so allow enough space for the full translated term in localized content.
Navigate
  • In most situations, avoid navigate and navigation, because they're formal words that might not localize well.
  • To describe going directly to a webpage or a place in the UI, use go to.
  • To describe moving through a page, file, or app, use move through.
  • Don't use navigation pane or navigation menu unless the term appears in the UI. Use left pane or left menu instead. Never use nav.
Open
  • Use for apps, panes, files, folders, and shortcut menus.
  • Don't use for commands and menus.
Select
  • Use to instruct the user to select an item, such as a button, a checkbox, a value in a list, a link, a menu item, or a key.
  • 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).
Turn on, turn off
  • Use for toggles.
  • Example - Turn on the Pass all filters toggle.

Localization​

UI elementUsage
Units of measure
  • Use numerals for measurement of distance, temperature, volume, size, weight, pixels, points, and so 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).