Google Developer Documentation Style Guide vs Microsoft Writing Style Guide: A Practical Comparison

In professional software documentation, consistency is not a cosmetic luxury; it is the cornerstone of trust. When a developer encounters one page using second person ("you configure the endpoint"), another using passive voice ("the endpoint must be configured by the administrator"), and a third using first-person plural ("in this guide we will configure"), cognitive load multiplies and the documentation feels fragmented.

To eliminate inconsistency, the software industry relies on two monumental, open-source editorial authorities:

1. The Google Developer Documentation Style Guide


2. The Microsoft Writing Style Guide

Both style guides aim for clarity, accessibility, and precision. However, their design philosophies, tonal recommendations, and formatting conventions diverge in significant ways. In this guide, we analyze both standards side-by-side.

###CODEBLOCKPLACEHOLDER0###

1. Rule-by-Rule Direct Comparison

A. Heading Capitalization

• Google Developer Style: Strictly Sentence Case for all headings and document titles. Capitalize only the first word and proper nouns.
• Google Example: Configure mutual TLS for ingress controllers
• Rationale: Sentence case is easier to read, avoids ambiguity over whether short prepositions (e.g., "with", "from") should be capitalized, and simplifies localization into European languages.
• Microsoft Style: Recommends Sentence Case for web documentation, but historically permitted Title Case for marketing headlines and product titles.
• Industry Consensus: Most modern developer portals standardize on Google's sentence-case rule for all technical documentation headings.

B. Voice, Person, and Tone

• Google Developer Style:
• Second Person ("You"): Address the reader directly as "you". Never use "we" (the royal we) or "the user".
• Active Voice: The subject must perform the action. Avoid passive constructions.
• Avoid: "The database cluster is provisioned by the worker node."
• Use: "The worker node provisions the database cluster."
• Imperative Mood for Instructions: Start instructional steps with active verbs: "Click", "Run", "Specify", "Download".
• Microsoft Style:
• Shares the emphasis on second person and active voice, but places stronger emphasis on a warm, conversational, and empathetic tone.
• Encourages contractions ("it's", "you'll", "don't") to make documentation sound natural and human, whereas Google allows contractions judiciously but warns against overusing them in formal API references.

C. The Oxford (Serial) Comma

• Google Developer Style: Mandatory. Always use the serial comma before the coordinating conjunction in lists of three or more items.
• Google Example: "Deploy the container, inspect the ingress logs, and verify the health check probe."
• Rationale: Eliminates grammatical ambiguity in technical specifications where compound list items could be misinterpreted as a single entity.
• Microsoft Style: Mandatory. Microsoft also requires the Oxford comma in all technical and consumer documentation.

D. Formatting UI Elements, Code Symbols, and File Paths

Content Type	Google Style Guide Rule	Microsoft Style Guide Rule	Example
Code identifiers (functions, classes)	Inline backtick code font	Inline backtick code font	` TelemetryClient
File paths and directories	Inline backtick code font	Inline backtick code font	/etc/dtw/config.yaml
UI buttons and menus	Bold text	Bold text	Click Save Changes
Keyboard shortcuts	or Bold + Key name	Bold key names with plus sign	Press Ctrl+C
Terminal command prompts	Omit the $ prefix in snippets	Omit the $ prefix	npm install @dtw/cli`

Notice the critical consensus on terminal prompts: Both Google and Microsoft strictly instruct writers never to include the $ or > command prompt symbol inside copy-pasteable terminal blocks. When a developer clicks the copy button, including $ causes the pasted command to fail with a syntax error in their terminal!

2. Inclusive Language and Global Accessibility Standards

Both style guides lead the technology industry in advocating for inclusive, bias-free, and accessible technical communication:


• Gender-Neutral Pronouns: Always use singular "they" or rephrase sentences to avoid gendered pronouns ("he" or "she").


• Culturally Inclusive Terminology: Replace militaristic, colonial, or exclusionary jargon with precise technical equivalents:


• Replace whitelist / blacklist with allowlist / denylist.


• Replace master / slave with primary / secondary or leader / follower.


• Replace sanity check with coherence check or quick validation.


• Replace dummy data with sample data or synthetic test values.


• Screen Reader Considerations: Avoid relying on visual-only directional instructions like "in the box on the right" or "click the green icon above". Always describe elements by their functional label: "Select the Deploy button in the navigation toolbar."


• Descriptive Link Text: Never write "click here" or "learn more". Screen reader users navigate pages by listening to a list of links out of context. Always use descriptive hyperlink text: "For authentication parameters, review the OpenAPI Authentication Guide."

3. Formatting Numbers, Dates, and Technical Units

Precision in numbers and dates prevents international operational misinterpretations:

4. Words to Avoid: Anti-Patterns in Technical Writing

Both style guides wage war against condescending, wordy, or culturally insensitive words. Below is a compiled dictionary of prohibited terms and recommended replacements:

5. Automating Enforcement via Vale Style Rules

Memorizing hundreds of style guide rules is impossible for software engineers submitting sporadic documentation pull requests. Automate compliance using Vale:

###CODEBLOCKPLACEHOLDER1###

###CODEBLOCKPLACEHOLDER2###

6. Deprecation Notices and Breaking Change Warnings

How you warn developers about imminent breaking changes or phased API retirements dictates whether migrations proceed smoothly or trigger angry customer support escalations:

7. Spelling, Hyphenation, and Tech Compound Words

Punctuation and compound word consistency distinguish professional developer portals from hurried blog posts:

8. Synthesis: Building an Organization Style Guide

Rather than authoring an internal style guide from scratch, modern technology companies adopt an existing foundation and document explicit company overrides:

###CODEBLOCKPLACEHOLDER4###

By standardizing on proven style guides and automating rule enforcement in CI, your technical documentation maintains a unified, professional voice across hundreds of contributors.