Microsoft Style Guide — Accessibility and Clarity in Technical Documentation

In this tutorial, you will learn about Microsoft Style Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

The Microsoft Style Guide emphasizes Accessibility, inclusive language, and writing for global audiences. It provides extensive guidance on making documentation usable for people with disabilities and non-native English speakers.

In this lesson, you will learn the key rules from Microsoft's guide and how to apply them.

What You'll Learn

You will understand Microsoft's approach to accessibility and inclusive language, apply its writing-for-translation rules, and know when to use its guidance over other guides.

Why It Matters

Microsoft's guide excels where other guides are weaker: accessibility, inclusive language, and Internationalization.

Real-World Use

DodaTech adopted Microsoft's accessibility guidelines to ensure documentation works with screen readers. The inclusive language rules also guided the terminology update from deprecated terms.

flowchart LR
  A[Microsoft Style Guide] --> B[Accessibility]
  A --> C[Inclusive Language]
  A --> D[Write for Translation]
  B --> E[Screen Reader Ready]
  B --> F[Descriptive Links]
  C --> G[Avoid Bias]
  C --> H[Use They]
  D --> I[Short Sentences]
  D --> J[No Idioms]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Accessibility Rules

Use descriptive alt text for all images. Alt text should describe the content and function of the image, not just its appearance.

Ensure color is not the only way to convey information. Add text labels or patterns for color-coded information.

Use meaningful link text. The DodaZIP installation guide not Click here. Screen reader users navigate by links.

Use proper heading hierarchy. Do not skip levels. Use h1 for title, h2 for sections, h3 for subsections.

# Microsoft Style: Accessibility

# Good alt text
![DodaZIP command line output showing compression ratio of 24.6%]

# Bad alt text
![Screenshot]

# Good heading hierarchy
## Installation
### System Requirements
### Step-by-Step Guide

# Bad heading hierarchy
## Installation
#### System Requirements (skipped h3)

Inclusive Language

Replace master and slave with primary and replica. Replace whitelist and blacklist with allowlist and denylist.

Use singular they for generic references. Each user should configure their settings is correct.

Avoid ableist language. Replace crazy with unexpected, crippling with severely limiting, blind to with unaware of.

# Microsoft Style: Inclusive Language

# Use these terms
- Primary server, replica server
- Allowlist, denylist
- They as singular pronoun

# Avoid these terms
- Master, slave
- Whitelist, blacklist
- He as generic pronoun

Writing for Translation

Keep sentences under 20 words. Short sentences translate more accurately.

Avoid idioms and cultural references. Piece of cake, hit the ground running, and cutting edge do not translate.

Use unambiguous dates. June 20, 2026 not 06/20/26 which means different things in different regions.

Specify units. 100 MB not just 100. Avoid directional references like as shown above.

# Microsoft Style: Write for translation

# Hard to translate
# This approach is a game-changer for developers who want to hit
# the ground running with compression.

# Easy to translate
# This approach helps developers add compression to their Python
# projects quickly. You can compress a file in three lines of code.

Common Mistakes

1. No Alt Text

Images without descriptions are invisible to screen reader users.

2. Color-Only Information

Using red text for warnings without adding Warning label.

3. Idioms in International Content

Using phrases that do not translate literally.

4. Ambiguous Dates

Using 06/20/26 which could be June 20 or June 6 depending on region.

5. Outdated Terminology

Still using whitelist and blacklist.

6. No Heading Hierarchy

Using headings out of order or for visual formatting only.

7. Referring to Visual Position

As shown above or in the following screenshot. Use specific references.

Practice Questions

1. What are Microsoft's key accessibility rules?

Descriptive alt text, color not the only indicator, meaningful link text, proper heading hierarchy.

2. How should you write for translation?

Short sentences, no idioms, unambiguous dates, specify units, avoid directional references.

3. What is wrong with whitelist and blacklist?

They have racial connotations. Use allowlist and denylist instead.

4. Why should dates be written as June 20, 2026?

Numeric dates are ambiguous. Different regions interpret month and day differently.

5. Challenge: Audit a documentation page against Microsoft's accessibility rules. Identify five issues and fix each one.

FAQ

Mini Project

Take a documentation page and evaluate it against three Microsoft Style Guide sections: accessibility, inclusive language, and writing for translation. Identify violations in each category. Rewrite the page applying Microsoft's rules.

What's Next

Next: Apple Style Guide