Why this deep dive exists
Every doc team eventually has the comma argument. And the "is it e-mail or email" argument. And the "do we capitalize the product name mid-sentence" argument. A style guide ends all of them at once, not by being right, but by being decided. This deep dive helps you decide fast and get back to writing.
Why adopt one at all 10 min
A style guide's value is not correctness. It is the end of relitigation. Once "serial comma, always" is written down, no reviewer spends a comment on it ever again.
Self-studyAdopting beats authoring3 min▶
Writing your own full style guide is a multi-month project that produces a document nobody reads. Adopting an existing one takes an afternoon and comes with a linter package for free. Both Google and Microsoft ship as Vale packages, so from Session 7 your CI can enforce either the day you pick it.
- The reference hierarchy: a short project style sheet (your local exceptions) sits on top of the adopted guide, which sits on top of a dictionary. Check the most specific first.
- Editing becomes mechanical. With a guide adopted, most review comments become "see the style guide" instead of a debate. That is the whole point.
- Consistency reads as competence. A doc set that handles commas, capitalization, and code font the same way everywhere feels trustworthy, even before anyone judges the content.
The consensus core 10 min
Here is the good news that saves the argument: on the mechanics, Google and Microsoft agree almost completely. These are industry consensus. Adopt them from either guide and stop debating them forever.
Self-studyThe twelve settled mechanics4 min▶
Both guides say the same thing on all of these. Treat them as decided:
| Rule | Both guides |
|---|---|
| Person | Second person "you" |
| Voice | Active, actor first |
| Tense | Present; avoid "will" for behavior |
| Headings | Sentence case, no end punctuation |
| Commas | Serial / Oxford comma always |
| Contractions | Fine, and friendly |
| Code and UI | Code font for code, bold for UI elements |
| Accessibility | Alt text; never rely on color alone |
| Spelling | US spelling, plain global English |
| Links | Descriptive text, never "click here" |
If your team is arguing about any row above, the argument is already settled by both authorities. Point at the table and move on.
The deltas, and the decision 15 min
The genuine differences are few, and they map cleanly to what you write. Know them and the choice makes itself.
Self-studyGoogle's edge: anti-hype and depth4 min▶
Google's guide is a pure developer-docs rulebook, and it carries a few disciplines Microsoft's does not emphasize:
- Anti-hype and timeless docs. No marketing claims, no pre-announcing features, and avoid time-bound words like "currently", "new", or "soon". "Pulse currently supports four event types" ages the day a fifth ships; "Pulse supports these event types" stays true.
- Conditions before instructions. "If the staged folder is empty, run ingest.py" not "run ingest.py if the folder is empty". The reader needs the condition before the action.
- Placeholder convention and interface depth. Capitalized italic code for placeholders (PROJECT_ID), plus deep coverage of command-line syntax, API reference comments, and reserved example domains.
Self-studyMicrosoft's edge: voice and pedagogy4 min▶
Microsoft's guide covers all communication, not just developer docs, and teaches differently:
- A branded voice. "Warm and relaxed, crisp and clear, ready to lend a hand" - useful when your docs sit next to product and marketing copy and need to sound like one company.
- Rewrite pedagogy. The Top 10 tips teach through before/after pairs. The classic: "If you're ready to purchase Office 365 for your organization, contact your Microsoft account representative" becomes "Ready to buy? Contact us." You learn by seeing the cut.
- Breadth. Per-topic checklists, a full bias-free communication section, and coverage of chatbots, responsive content, and SEO - plus process pages for planning and publishing review.
Self-studyThe decision rule3 min▶
It comes down to what you mostly write:
- Developer docs, APIs, CLIs, READMEs - adopt Google. It is built for exactly this, and its anti-hype and placeholder rules pay off immediately.
- Product UI text, help centers, mixed marketing-adjacent content - adopt Microsoft. Its voice and breadth cover the ground Google leaves out.
- Either way, adopt one. The worst choice is no choice. Vale ships both as packages, so enforcement costs nothing once you decide.
Self-studyDecide it for Pulse2 min▶
Pulse is a developer pipeline documented for analysts and engineers - squarely developer docs. So the decision is Google, and you record it in one line of DOCS.md. The nice part: Vale has been linting Pulse's docs with the Google package since Session 7, so the choice was already half-made. This deep dive just names it and writes it down. Full circle.
The team that adopted both and shipped neither. One org spent two sprints comparing the guides line by line to build a "best of both" custom guide. It was never finished, so reviewers kept arguing anyway. A team next door adopted Google verbatim in an afternoon, added a 6-line project sheet, and never had the comma argument again. Decided beats perfect.
Try it yourself ◐ 30 min
- Classify your team's writing: mostly developer docs, mostly product/UI, or a real mix. Let that pick your guide, then write the one-line adoption into your docs home.
- Draft your 5-line project style sheet: adopted guide, terminology exceptions, product-name rule, date format, and the one local rule your team fights about most.
- Wire the matching Vale package into CI (you set the pattern up in Session 7). Run it on one real doc and read the output.
- Optional depth: skim the highlights pages - developers.google.com/style/highlights and Microsoft's Top 10 tips at learn.microsoft.com/style-guide.
Official sources covered
This deep dive synthesizes both style guides into a decision. The full A-to-Z word lists stay with the originals - they are reference works, not reading.
Three questions before you go 🎯 ◐ 90 seconds
1 · Your team argues about the serial comma. What's true?
The serial comma is in the consensus core. Both authorities agree, so the argument is already over.
2 · You mostly write API and CLI reference docs. Which guide?
Developer docs, APIs, and CLIs map to Google. Microsoft's edge is product/UI/mixed content.
3 · Which sentence violates Google's timeless-docs rule?
"Currently" and "coming soon" date the doc. Timeless docs avoid time-bound words that age the moment things change.