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