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

Style checklist

Use the following style checklist whenever you need to write something for the product. The following short guides, presented as a checklist, aim to assist you in developing consistent and clear content.

tip

This checklist is a summary. The Microsoft Style Guide is our only source of truth: if you're in doubt, check it and follow it. For more detailed information, refer to the Text craft section.

Style checklist for developers​

When creating the UI content, answer the following questions:

  • Is the content clear?

  • Does it use the present tense?

  • Does it use the second person (you, your)?

  • Is it free of jargon?

  • Is it free of big words?

  • Is it free of internal words?

  • Does it avoid quotation marks in UI text? If you need them, use straight double quotation marks (" ").

  • Does it use Omada Identity instead of OI?

  • Does it avoid acronyms that your users might not know?

  • Does it avoid Latin abbreviations? Use for example, that is, and and so on instead of e.g., i.e., and etc.

  • Does it use sentence-style capitalization? Capitalize only the first word and proper nouns in:

    • Sentences
    • Headings
    • Titles
    • UI labels
  • Does it avoid periods in:

    • Headings
    • Subheadings
    • UI titles
    • UI text
    • Simple lists (three or fewer words per item)

Style checklist for technical writers​

When creating any type of content, follow these guidelines.

The content must be:

  • Clear and direct

  • Human

  • Free of jargon

  • Free of big words and overly long sentences

Spelling

  • Acronyms: The first time you use an acronym, spell out the term and add the acronym in parentheses, for example, Role and Policy Engine (RoPE). Don't spell out well-known acronyms, such as API or URL.

  • Write Omada Identity, not OI.

  • Acronyms in titles and headings: Avoid using an acronym for the first time in a title or heading, unless it's a keyword that you need for SEO.

  • Use sentence-style capitalization. Capitalize the first word of a sentence, heading, title, or UI label.

  • Use lowercase for everything else, except proper nouns.

  • Slashes: Capitalize the word after a slash only if the word before it is capitalized (True/False, Country/Region).

  • Use the present tense.

  • Use the second person (you, your).

  • Use contractions, such as it's, you're, and don't.

  • Avoid Latin abbreviations. Use for example, that is, and and so on instead of e.g., i.e., and etc.

  • Use bold for:

    • Names of UI elements, such as buttons, checkboxes, boxes, menus, tabs, dialogs, and panes
    • Key names and keyboard shortcuts
    • UI paths (but not the > character)
    • Text that you tell the user to enter
  • Use code style for:

    • Markup language elements (tags)
    • Commands, code, and file paths in code
  • Use italic for:

    • New terms, on first mention, when you define them
    • Placeholders
    • Setting values (True/False)
    • Names of sections, documents, and guides
    • Emphasis (sparingly)

Punctuation

  • Colons: You can use a colon at the end of a phrase that introduces a list. Within a sentence, lowercase the word after a colon unless it's a proper noun. In titles and headings, capitalize the word after a colon. Don't end a title or heading with a colon.

  • Numbers: Spell out whole numbers from zero through nine. Use numerals for 10 or greater.

  • Commas: Use a comma before the conjunction in a list of three or more items (serial comma), after an introductory phrase, and to join independent clauses with a conjunction.

  • Em dashes: Use them to set off a break in thought or a clarification. Don't add spaces around an em dash, and don't overuse em dashes.

  • En dashes: Use them for ranges of numbers and dates, such as 2015–2017. Don't use an en dash for negative numbers. Use the minus sign (−) instead.

  • Hyphens: Hyphenate two or more words that come before a noun and modify it as a unit, such as built-in drive. Don't hyphenate after very or after adverbs ending in -ly.

  • Ellipses: Use them only to indicate omitted text.

  • Periods: End all sentences with a period. Don't use periods in:

    • Headings
    • Subheadings
    • UI titles
    • UI text
    • Simple lists (three or fewer words per item)
  • Quotation marks: Use straight double quotation marks (" "). Use single quotation marks (' ') only for a quotation inside a quotation.