Developer Documentation Style Guide

Google · 2017–present · Read the guide (CC BY 4.0)

Every style guide before this one said “use the active voice.” None of them said when not to. Google’s guide is the first to enumerate the exceptions: use passive when you want to emphasize the object, when you want to de-emphasize the subject, or when the actor is irrelevant. Three cases. Falsifiable. Now the rule is precise enough to follow.

The argument

Google’s style guide emerged from the practical problem of writing documentation at scale. Thousands of engineers writing docs for millions of readers. The guide was written for engineers, but the breakthrough applies to any team that writes: precise rules produce consistent output. The question was practical: how do you get consistent output from inconsistent writers? Strunk’s rules are too vague to enforce. “Use the active voice” means different things to different people. One writer reads it as “never use passive.” Another reads it as “prefer active when possible.” Neither is wrong, and the outputs diverge.

Google’s solution: make every rule precise enough that two writers reading the same rule produce the same output. The guide covers voice, tense, word choice, formatting, accessibility, and more. But the active voice section is the breakthrough. It takes a rule that’s been vague since 1918 and makes it mechanically applicable. The rule became “use active voice unless one of these three conditions holds”: a decision procedure, not an aspiration.

This is what it means for a rule to be precise. A precise rule takes a sentence and produces a clear answer: active or passive. A vague rule takes a sentence and produces a judgment call. Judgment calls don’t scale. Clear answers do.

The three exceptions

Exception	When to use passive	Example
Emphasize the object	The thing acted on matters more than the actor	“The file is deleted when you close the app.” The file matters, not the system.
De-emphasize the subject	The actor is awkward or distracting to name	“The logs are written to /var/log.” Naming the logging daemon adds nothing.
Actor is irrelevant	Who does it doesn’t matter	“The page is loaded.” Browser, CDN, cache: the reader doesn’t care which.

Discussion

Voice choice is now falsifiable. Three exceptions, each with a clear test: is the object more important than the actor? Is the actor distracting to name? Is the actor irrelevant? You can check each condition and arrive at an answer. You can also check whether someone else followed the rule. That’s the difference between a guideline and a specification.

The guide also treats text as something processed by both humans and machines. Screen readers, translation tools, and search indexes all parse the same sentences your readers do. Short sentences translate better. Active voice parses more reliably. Consistent terminology improves search. Clarity for human readers and survival through mechanical transformation turn out to require the same things. This dual audience is exactly the constraint behind vibelogging: prose that is parseable by both humans and LLMs.

The deeper point: vague rules produce inconsistent output. Precise rules produce consistent output. Every discipline that has matured — engineering, law, accounting — has made this transition. Prose style was late. Google’s guide is the first serious attempt to catch up. The frontier is better specification.

Developer Documentation Style Guide

The argument

The three exceptions

Discussion

See also