Technical Writing and Documentation 101: Style Guides (Microsoft Manual of Style, Google Developer Docs Style Guide, Chicago)

Style Guides (Microsoft Manual of Style, Google Developer Docs Style Guide, Chicago)

Style Guides for Technical Writers: A Portfolio-Ready Study Guide

(Microsoft Manual of Style, Google Developer Docs Style Guide, Chicago Manual of Style)

What This Is

A style guide is a rulebook for writing clear, consistent, and professional technical documentation. It ensures that every doc—whether an API reference for a payment gateway (like Stripe’s), a getting-started guide for AWS Lambda, or a CLI tool’s help text—follows the same tone, terminology, and formatting. Without one, docs become confusing (e.g., calling a "user" a "customer" in one section and a "client" in another), frustrating users and increasing support tickets. Style guides also save time: instead of debating whether to write "log in" or "login," you follow the guide and move on.

Key Terms & Tools

• Microsoft Manual of Style (MSTP):
  The industry standard for software documentation (Windows, Azure, Office). Focuses on clarity, conciseness, and user-first language (e.g., "Select Save" instead of "Click the Save button"). Used for UI text, error messages, and end-user docs.

• Google Developer Docs Style Guide:
  A minimalist, opinionated guide for developer-facing content (APIs, SDKs, CLI tools). Prioritizes scannability (short sentences, active voice) and code-first examples (e.g., "Use gcloud compute instances create to launch a VM"). Includes rules for Markdown, OpenAPI specs, and CLI docs.

• Chicago Manual of Style (CMOS):
  The publisher’s bible for grammar, punctuation, and citations. Used for long-form content (whitepapers, books, blog posts) and formal documentation (e.g., IBM’s Redbooks). Less tech-specific but essential for academic or marketing-adjacent docs.

• Style Guide vs. Tone Guide:

• Style Guide: Rules for grammar, formatting, and terminology (e.g., "Use ‘sign in’ as a verb, ‘sign-in’ as an adjective").

• Tone Guide: Rules for voice and personality (e.g., "Be friendly but not cutesy; avoid humor in error messages").

• Docs-as-Code:
  Treating docs like code—stored in Git, written in Markdown/AsciiDoc, reviewed via PRs, and built with static site generators (e.g., Hugo, Docusaurus). Enables automated style checks (e.g., Vale, textlint) to enforce style guide rules.

• Vale:
  An open-source linter for prose. Scans docs for style guide violations (e.g., passive voice, jargon) and integrates with CI/CD pipelines. Example rule: "Flag ‘utilize’; prefer ‘use.’"

• Markdown:
  A lightweight markup language for formatting docs (e.g., # Heading, bold, [link](url)). Used in GitHub, GitLab, and most docs-as-code workflows.

• OpenAPI (Swagger):
  A specification for describing REST APIs. Style guides (like Google’s) include rules for OpenAPI YAML/JSON files (e.g., "Use snake_case for parameter names, PascalCase for schema objects").

• DITA (Darwin Information Typing Architecture):
  An XML-based standard for structured authoring (used in enterprise docs like Cisco’s). Enforces modular writing (topics, not pages) and reusability (e.g., a single "installation" topic used in multiple guides).

• Static Site Generators (SSGs):
  Tools like Hugo, Docusaurus, or Sphinx that convert Markdown/AsciiDoc into HTML websites. Often paired with style guides to enforce consistency (e.g., "All code blocks must have syntax highlighting").

• Terminology Management:
  Tools like Acrolinx, TermWeb, or even a shared spreadsheet to define and enforce approved terms (e.g., "Never use ‘abort’; use ‘cancel’ or ‘stop’"). Critical for globalized docs (e.g., avoiding idioms like "bite the bullet").

• Accessibility (a11y):
  Style guides include rules for inclusive writing (e.g., "Avoid ‘see’ for blind users; use ‘read’ or ‘review’"). Tools like axe or WAVE can audit docs for a11y compliance.

Step-by-Step: How to Apply a Style Guide

1. Choose the Right Guide for Your Audience

• Developer docs? → Google’s guide (minimalist, code-first).
• End-user software? → Microsoft’s guide (UI-focused, user-friendly).
• Formal/long-form content? → Chicago (grammar, citations).
• Custom guide? → Adapt one of the above (e.g., "We follow Google’s guide but use ‘customer’ instead of ‘user’").

2. Set Up Automated Enforcement

• For docs-as-code:
• Install Vale and configure it with your style guide’s rules (e.g., Google’s Vale rules).
• Add Vale to your CI/CD pipeline (e.g., GitHub Actions) to block PRs with style violations.
• Example .vale.ini rule:
  ini
[Google.PassiveVoice]
BasedOn = Google
• For DITA/XML:
  Use Schematron or Oxygen XML Editor to validate against style rules (e.g., "All <step> elements must start with a verb").

3. Audit Existing Docs

• Manual audit:
• Pick a sample doc (e.g., an API reference or CLI guide).
• Check for consistency (e.g., "Is ‘log in’ always two words?").
• Check for clarity (e.g., "Is ‘utilize’ replaced with ‘use’?").
• Automated audit:
  Run Vale or textlint on your docs repo to generate a report of violations.
  Example Vale output: ``` 1 warning in README.md:
  • Google.PassiveVoice: "The button was clicked" → "Click the button." ```

4. Write or Rewrite with the Guide in Mind

• For API docs:
• Follow Google’s guide for OpenAPI specs (e.g., "Use description fields for human-readable text, not implementation details").
• Example OpenAPI snippet (correct):
  ```yaml
  parameters:
  • name: user_id
    in: path
    description: The ID of the user to fetch. Must be a UUID.
    required: true
    schema:
    type: string
    format: uuid ```
• For UI text:
• Follow Microsoft’s guide (e.g., "Use sentence case for button labels: ‘Save changes’ not ‘Save Changes’").
• For tutorials:
• Follow Google’s guide (e.g., "Start with a goal: ‘In this tutorial, you’ll deploy a Node.js app to Cloud Run.’").

5. Get Team Buy-In

• For engineers:
• Explain how style guides reduce support tickets (e.g., "Consistent error messages mean fewer confused users").
• Show before/after examples (e.g., a messy API doc vs. one following Google’s guide).
• For product managers:
• Highlight brand consistency (e.g., "Our docs should sound like us, not like 10 different writers").
• For legal/compliance:
• Note risk reduction (e.g., "Avoiding ambiguous terms like ‘may’ in legal-adjacent docs").

6. Maintain the Guide

• Add a "Contributing" section to your docs repo with:
• A link to the style guide.
• Instructions for running Vale/textlint.
• A terminology glossary (e.g., "Use ‘container’ not ‘Docker image’ unless referring to the Docker-specific format").
• Schedule quarterly reviews to update the guide (e.g., "We now support WebAssembly; add rules for WASM-related terms").

Common Mistakes

Mistake 1: Treating the Style Guide as Optional

• Correction:
  Enforce it automatically (e.g., Vale in CI/CD) and socially (e.g., "All PRs must pass Vale checks"). Why? Inconsistent docs erode trust—users assume sloppy docs mean sloppy code.

Mistake 2: Ignoring the Audience

• Correction:
  Google’s guide is for developers; Microsoft’s is for end users. Don’t use "utilize" in a CLI guide (Google says no) or "click" in an API doc (Microsoft says yes for UIs, but APIs are code-driven). Why? Jargon alienates users; plain language empowers them.

Mistake 3: Over-Editing for "Perfection"

• Correction:
  Focus on clarity and consistency, not grammar pedantry. Example: Google’s guide allows fragments in UI text (e.g., "No results found.") if it’s clearer. Why? Users scan docs; they don’t read them like novels.

Mistake 4: Not Documenting Exceptions

• Correction:
  If your team must break a rule (e.g., "We use ‘login’ as a noun because our API does"), document it in the guide. Example:

  Exception: In the Auth API, use "login" as a noun (e.g., "Create a login token") to match the codebase. Elsewhere, use "sign-in."

  
  

Why? Undocumented exceptions lead to inconsistency by stealth.

Mistake 5: Forgetting Localization

• Correction:
  Style guides should include localization rules (e.g., "Avoid idioms like ‘hit the ground running’; use ‘start quickly’"). Tools like Phrase or Lokalise can flag non-localizable terms. Why? A guide that works in English may fail in Japanese or German.

Tech Writing Interview / Portfolio Tips

1. Show You Understand the "Why" Behind Rules

• Hiring managers test this with:
• "Why does Google’s guide ban passive voice?"
• "When would you break Microsoft’s rule about sentence case for buttons?"
• How to answer:
• Passive voice: "It obscures who’s doing the action. ‘The file was uploaded’ → ‘You uploaded the file’ is clearer for users."
• Button case: "If the button label is a proper noun (e.g., ‘GitHub Actions’), capitalize it for brand consistency."

2. Differentiate Between Style Guides

• Tricky distinction: Microsoft vs. Google vs. Chicago
• Microsoft: Best for UI text, error messages, and end-user docs (e.g., "Select Save to store your changes.").
• Google: Best for developer docs, APIs, and CLI tools (e.g., "Use gcloud auth login to authenticate.").
• Chicago: Best for long-form, formal, or published content (e.g., a whitepaper on cloud security).

3. Include Style Guide Work in Your Portfolio

• What to show:
• A before/after rewrite of a doc using a style guide (e.g., "Here’s a messy API doc; here’s the same doc following Google’s guide").
• A custom style guide you created (e.g., for a hackathon project or open-source tool).
• A Vale configuration file or CI/CD pipeline that enforces style rules.
• Example portfolio item:

  Project: "Rewrote the Acme API docs using Google’s style guide" - Audited 50+ endpoints for consistency (e.g., "Ensured all description fields used active voice").
  - Added Vale to the docs repo to block PRs with style violations.
  - Reduced support tickets by 20% (data from Acme’s help desk).

  
  

4. Know the Tools

• Hiring managers ask:
• "How would you enforce a style guide in a docs-as-code workflow?"
• "What’s the difference between Swagger UI and ReDoc?"
• How to answer:
• Enforcement: "Use Vale for prose, Spectral for OpenAPI specs, and GitHub Actions for CI/CD."
• Swagger UI vs. ReDoc:
  • Swagger UI: Interactive, good for testing APIs, but heavier.
  • ReDoc: Static, faster, better for production docs.

Quick Check Questions

1. A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?

Answer:
Use docs-as-code with automated checks: - Store docs in the same repo as the code.
- Add OpenAPI specs to the codebase and validate them with Spectral in CI/CD.
- Use Git hooks or GitHub Actions to block PRs if docs don’t match the code (e.g., "This endpoint’s description doesn’t match the OpenAPI spec").
Why? Manual updates always lag; automation keeps docs in sync.

2. Your team can’t agree on whether to use "log in" or "login." How do you decide?

Answer:
Check the style guide: - Microsoft’s guide: "log in" (verb), "sign-in" (noun/adjective).
- Google’s guide: "sign in" (verb), "sign-in" (noun/adjective).
If no guide applies, document the decision in your team’s style guide and enforce it with Vale.
Why? Consistency > personal preference.

3. A PM asks you to write a "tutorial" for a new feature. What’s the first question you ask?

Answer:
"What’s the user’s goal?"
- A tutorial teaches concepts by building (e.g., "Build a weather app with our API").
- A how-to guide solves a specific problem (e.g., "How to set up OAuth").
Why? Mislabeling docs confuses users (e.g., a "tutorial" that’s just a list of steps).

Last-Minute Cram Sheet

1. Microsoft Manual of Style: UI text, end-user docs, error messages. Rule: "Use sentence case for buttons: ‘Save changes’."
2. Google Developer Docs Style Guide: APIs, CLI tools, developer docs. Rule: "Use active voice: ‘The system deletes the file’ → ‘Delete the file.’"
3. Chicago Manual of Style: Grammar, citations, long-form content. Rule: "Use the serial comma: ‘red, white, and blue.’"
4. Docs-as-Code: Store docs in Git, write in Markdown, review via PRs. Tool: Vale for style checks.
5. OpenAPI: Describe REST APIs in YAML/JSON. Rule: "Use snake_case for parameters, PascalCase for schemas."
6. Vale: Linter for prose. Rule: "Flag ‘utilize’; prefer ‘use.’" Config: .vale.ini.
7. Markdown: # Heading, bold, [link](url). Quirk: Backticks for code.
8. DITA: XML-based structured authoring. Rule: "Write in topics, not pages."
9. ⚠️ Tutorial vs. How-To: Tutorial = teach by building; how-to = solve a problem.
10. ⚠️ Passive Voice Trap: "The file was uploaded" → "You uploaded the file." (Google’s guide bans passive voice.)