Technical Style Guides: Consistent Documentation Standards

A technical style guide is a set of standards for writing documentation — covering voice, tone, terminology, formatting, and grammar. It ensures every page reads like it was written by one author, even when dozens of people contribute.

In this tutorial, you’ll learn about the most popular style guides, how to enforce them automatically with tools like Vale, and how to create your own style guide for your project or organization.

What a Style Guide Covers

    flowchart TD
  A[Style Guide] --> B[Voice & Tone]
  A --> C[Terminology]
  A --> D[Grammar & Mechanics]
  A --> E[Formatting]
  A --> F[Internationalization]
  B --> G[Active voice]
  B --> H[Second person]
  B --> I[Inclusive language]
  C --> J[Word list]
  C --> K[Capitalization]
  C --> L[Product names]
  D --> M[Punctuation]
  D --> N[Contractions]
  D --> O[Lists]
  E --> P[Headings]
  E --> Q[Code formatting]
  E --> R[Images]
  F --> S[Locale]
  F --> T[Date/time format]
  F --> U[Currency]
  A:::current

  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
  

Major Style Guides

Google Developer Documentation Style Guide

Google’s guide is the most comprehensive for technical writing. Key rules:

• Active voice — “The API returns a list of users” not “A list of users is returned”
• Second person — “You can install the package” not “The user can install the package”
• Present tense — “The function accepts a string” not “The function will accept”
• Short sentences — Aim for 20 words or fewer

Microsoft Style Guide

Microsoft’s guide emphasizes accessibility and clarity:

• Use “you” — Address the reader directly
• Avoid jargon — Explain terms when first used
• Use “can” for ability — “You can configure the API”
• Use “may” only for permission — “You may use this feature if your license includes it”
• Write for translation — Avoid idioms and cultural references

Apple Style Guide

Apple focuses on user experience and simplicity:

• Task-oriented — “Set up your account” not “Account setup”
• Avoid file extensions — “Open the document” not “Open the .docx file”
• Use menu paths — “Choose File > Save” not “Click File then Save”
• Consistent terminology — Always “tap” on iOS, “click” on macOS

Voice and Tone Guidelines

Active Voice

Active voice makes sentences clearer and shorter:

Second Person

Write directly to the reader:

✅ You can create a new project by clicking "New Project" in the dashboard.
❌ The user can create a new project by clicking "New Project" in the dashboard.

Inclusive Language

• Use “they” as a singular pronoun
• Avoid “master/slave”, “whitelist/blacklist” — use “primary/replica”, “allowlist/denylist”
• Use “stakeholders” instead of “guys”
• Avoid ableist language: “crazy”, “crippling”, “blind to”

Terminology Management

Maintain a word list that defines preferred terms:

Formatting Conventions

Headings

• Use sentence case for headings: “Setting up your development environment”
• One ## H2 per main concept
• Never skip heading levels: ## → ### → ####

Code Formatting

• Use backticks for inline code: npm install
• Use code blocks for multi-line examples with language tags
• Always show expected output

Lists

• Use numbered lists for sequential steps
• Use bullet lists for non-sequential items
• Capitalize the first word of each list item
• End each item with a period if it’s a complete sentence

Internationalization (i18n)

If your docs are translated, write for translatability:

• Keep sentences short (20 words max)
• Avoid idioms: “piece of cake”, “hit the ground running”
• Use unambiguous dates: “June 20, 2026” not “06/20/26”
• Specify units: “100 MB” not just “100”
• Use standard date/time formats in code examples: ISO 8601

Automated Style Checking with Vale

Vale is a prose linter that enforces style rules automatically. Create a .vale.ini file:

StylesPath = .vale/styles
MinAlertLevel = suggestion

[*]
BasedOnStyles = Vale, Google, Microsoft

Then add style rules in YAML:

# .vale/styles/Google/ActiveVoice.yml
extends: existence
message: "Use active voice instead of '%s'."
link: https://developers.google.com/style/voice
level: warning
ignorecase: true
tokens:
  - is used
  - are used
  - is shown
  - are shown
  - can be found

Run Vale in CI to catch issues automatically:

vale content/
# content/api-docs.md:23:1  warning  Use active voice instead of 'is used'.
# content/api-docs.md:45:12  error  Use 'sign in' instead of 'login'.

Creating Your Own Style Guide

For most projects, adapting an existing guide is enough. But when you need custom rules:

1. Start with Google or Microsoft — Pick the closest match to your needs
2. Add project-specific rules — Product names, API terminology, brand voice
3. Include examples — Show good and bad examples for each rule
4. Make it living — Store in Git, update via pull requests, review annually
5. Automate enforcement — Configure Vale with your custom rules

# DodaTech Style Guide Additions

## DodaTech Product Names

- Doda Browser (not Doda browser or DodaBrowser)
- DodaZIP (all caps ZIP)
- Durga Antivirus Pro (capitalized)

## API Terminology

- Use "API key" not "token" for authentication
- Use "endpoint" not "route" for URLs
- Use "request body" not "payload"

Common Mistakes

1. No Style Guide at All

Every writer writes differently. Without a guide, documentation is inconsistent, confusing, and unprofessional.

2. Copying a Style Guide Without Adaptation

Google’s guide is excellent but may not fit your context. Adapt it — remove irrelevant rules, add project-specific ones.

3. Manual Enforcement Only

Relying on human reviewers to catch style issues is slow and inconsistent. Use Vale to automate common checks.

4. Ignoring Inclusive Language

Using outdated terms like “whitelist” or “master/slave” alienates readers and reflects poorly on your organization.

5. Contradictory Rules

“Use ’login’ as one word” in one section but “use ’log in’ as verb” in another. Consistent rules prevent confusion.

6. Style Guide Not Accessible

Style guide buried in a wiki that nobody reads. Store it alongside docs in the repository, link to it from CI output.

7. Never Updated

A style guide written in 2020 using examples from older frameworks. Review and update at least annually.

Practice Questions

1. What are the three most important voice and tone rules for technical documentation?

Active voice, second person (“you”), and present tense. These make documentation clearer and more direct.

2. How does Vale help maintain documentation standards?

Vale is a prose linter that checks documentation against configurable style rules. It catches inconsistencies, terminology errors, and passive voice automatically.

3. Why should you write for translation even if you don’t plan to translate?

Writing for translation forces short sentences, clear language, and no idioms — which makes documentation better for every reader, not just non-native speakers.

4. What should you include when creating your own style guide?

Adapted base rules from an existing guide (Google, Microsoft), project-specific terminology, formatting conventions, examples of good and bad writing, and automation configuration.

5. Challenge: Create a custom Vale style configuration for a real or hypothetical project. Define 10 project-specific rules covering terminology, voice, and formatting. Write a test document and verify Vale catches the violations.

Real-World Task

Audit an existing documentation set against the Google Developer Documentation Style Guide. Identify 10 violations and categorize them by type (voice, terminology, formatting). Create a plan to fix them and add Vale rules to prevent recurrence.

FAQ

What’s Next