Software and cloud services
Microsoft Writing Style Guide, annotated
Microsoft’s writing guide dates every page and gives each banned word a replacement and a reason. Its best rules on voice and words, quoted with notes.
The Microsoft Writing Style Guide is for everyone who writes about computer technology, in Microsoft or outside it. It describes the voice as “warm and relaxed, crisp and clear, and ready to lend a hand”. Most of the guide is a long A to Z of terms. Every page shows its own “Last updated on” date, and few guides do that.
Best parts, quoted with notes
Voice and tone
Warm and relaxed—We’re natural. Less formal, more grounded in real, everyday conversations. Occasionally, we’re fun. (We know when to celebrate.)
Has: where it applies. Names the trait, then caps the fun at ‘occasionally’.
Voice and tone
Though our voice is constant regardless of who we’re talking to or what we’re saying, we adapt our tone—from serious to empathetic to lighthearted—to fit the context and the customer's state of mind.
Has: where it applies. Separates fixed voice from changing tone and names the range, but gives no cases.
Voice and tone
Replace this: Invalid ID With this: You need an ID that looks like this: someone@example.com
Has: right and wrong. A before and after for an error message. The new message tells the user what to enter.
Words and style
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.
Has: exact value, reason, where it applies. Gives the replacement, the reason, and the one case where the old word is fine.
Words and style
Never use whitelist. Use allow list instead. For more specific usage, safe senders list can be used.
Has: exact value, date. A banned word with two replacements, on a page dated 01/15/2026. No reason given.
Words and style
If you can't write around the problem, it's OK to use a plural pronoun (they, their, or them) in generic references to a single person. Don't use constructions like he/she and s/he.
Has: exact value, where it applies. Sets an order: rewrite first, singular ‘they’ second. Bans he/she outright.
Words and style
Include articles, such as the. Articles help readers and translation software identify the nouns and modifiers in a sentence.
Has: reason. The reason counts software as a reader, not only people.
What it leaves out
- The brand voice page lists its three voice principles with no example sentences. The before and after examples are on the separate Top 10 tips page. Source
- The brand voice page says tone moves from serious to lighthearted but does not say which tone fits which situation. Source
What to take from it
- Put a date on every page, and not only on the guide. Then readers can see quickly if a rule is new.
- Give each banned word its replacement, and the case where the old word is still correct.
- Count software as a reader. Rules that help machine translation also help AI agents.