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.
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
| Element | Usage |
|---|---|
| Colons |
|
| Commas |
|
| Em dash | Use:
|
| En dash |
|
| Minus sign |
|
| Ellipses |
|
| Hyphens | Hyphenate two or more words that precede and modify a noun as a unit if:
|
| Periods |
|
| Numbers |
|
| Quotation marks |
|
Date and formats
| Date and format | Usage |
|---|---|
| 24/7 |
|
| AM, PM |
|
| Dates |
|
| Days of the week: Sunday–Saturday |
|
| Midnight, noon |
|
| Months: January–December |
|
| Time zones: Eastern Time, Central Time, Mountain Time, Pacific Time, Coordinated Universal Time (UTC), Greenwich Mean Time (GMT) |
|
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 element | Rule and example |
|---|---|
| > |
|
| Box |
|
| Button |
|
| Cancel |
|
| Checkbox |
|
| Choose |
|
| Click |
|
| Close |
|
| Cloud |
|
| Deinstall |
|
| Delete |
|
| Dialog |
|
| Download |
|
| Drag and drop |
|
| Enter |
|
| Exit |
|
| Extension |
|
| Field |
|
| File |
|
| File attributes |
|
| Finalize |
|
| Go to |
|
| Icon |
|
| Info |
|
| Navigate |
|
| Open |
|
| Select |
|
| Sign in, sign out |
|
| Turn on, turn off |
|
Localization
| UI element | Usage |
|---|---|
| Units of measure |
|
| Currency |
|
| URLs |
|