Google Developer Documentation Style Guide — Key Rules and Principles

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

The Google Developer Documentation Style Guide is the most comprehensive and widely adopted style guide for technical writing. It covers voice, tone, grammar, formatting, and code presentation with specific guidance for developer documentation.

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

What You'll Learn

You will understand the core principles of the Google Developer Style Guide, apply its key rules, and know where to find guidance for specific topics.

Why It Matters

Google's guide is the gold standard for developer documentation. Following it aligns your docs with what developers expect from professional documentation.

Real-World Use

DodaTech adopted Google's guide as the base for all product documentation. Consistency scores improved by 40 percentage points after implementing its rules.

flowchart LR
  A[Google Style Guide] --> B[Active Voice]
  A --> C[Second Person]
  A --> D[Present Tense]
  A --> E[Short Sentences]
  A --> F[Code Formatting]
  B --> G[The API returns]
  C --> H[You can install]
  D --> I[The function takes]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Core Voice Rules

Use active voice. The API returns a list of users, not A list of users is returned by the API. Active voice is shorter and clearer.

Use second person. Address the reader as you. You can install the package, not The user can install the package.

Use present tense. The function accepts a string, not The function will accept a string. Present tense feels immediate and authoritative.

# Google Style: Active Voice
- Good: The server validates the request.
- Bad: The request is validated by the server.

# Google Style: Second Person
- Good: You can create a new project by clicking New Project.
- Bad: The user can create a new project by clicking New Project.

# Google Style: Present Tense
- Good: When you click Save, the system validates the form.
- Bad: When you click Save, the system will validate the form.

Formatting Rules

Use sentence case for headings. Setting up your development environment, not Setting Up Your Development Environment.

Use numbered lists for sequential steps. Use bullet lists for non-sequential items.

Specify language tags for code blocks. Use python not just .

Use descriptive link text. See the installation guide, not Click here.

# Google Style: Code examples show expected output
def add(a: int, b: int) -> int:
    """Add two numbers and return the result."""
    return a + b

result = add(3, 5)
print(result)
# Expected: 8

Common Mistakes

1. Ignoring Google's Rule on Headings

Using title case instead of sentence case for headings.

2. Not Specifying Language in Code Blocks

Code blocks without language tags cannot get syntax highlighting.

3. Using Click Here for Links

Link text should describe the destination.

4. Mixing Voice

Starting active and switching to passive within the same document.

5. No Expected Output

Code blocks without expected output leave readers guessing.

6. Writing for The User Instead of You

Third person distances the reader.

7. Using Future Tense

The function will accept vs The function accepts.

Practice Questions

1. What are the three core voice rules in Google's style guide?

Active voice, second person, and present tense.

2. What case should headings use?

Sentence case. Only the first word and proper nouns are capitalized.

3. How should code blocks be formatted?

With language tags for syntax highlighting and expected output shown after.

4. What is the rule for link text?

Use descriptive text that tells the reader where the link goes. Not click here.

5. Challenge: Find a page that violates Google's style guide rules. Identify five specific violations and rewrite the page to follow the guide.

FAQ

Mini Project

Take a page from your documentation. Audit it against the Google Developer Style Guide. List every violation and rewrite the page to comply. Note which rules had the most impact on clarity.

What's Next

Next: Microsoft Style Guide