Google’s style guide for software developers
By Mike Pope and Jed Hartman
At Google, we produce a lot of documentation for software developers. We have hundreds of thousands of pages of documentation for Google Cloud products, Android, Google Maps, and other technologies.
You can imagine the challenge of trying to make all this text consistent and to make it sound like it comes from one company. The best tool we have for this challenge is the Google developer documentation style guide.
What it’s about
The style guide is a central resource for capturing Google style for developer documentation. As you’d expect, it records many small decisions. How do we write the plural of appendix? Is there a space in filename? How do we format text that refers to user interface elements in a web page? How do we capitalize page titles?
These questions come up frequently, and we want ready answers for our writers. Sometimes we echo other resources (such as The Chicago Manual of Style or the Merriam-Webster dictionary). But often the issues are unique to Google, and we need decisions that are pertinent to our documentation.
The guide also helps our writers steer clear of legal issues. For example, don’t make unsupported claims about what our products can do. Don’t allude to features that haven’t been released yet. Stick with the approved fictitious names, email addresses, and URLs. Don’t copy text from third-party sites.
Other topics in the style guide address how to write inclusively, for accessibility, and for a global audience.
Who it’s for
The style guide was conceived in 2005 as a resource for Google technical writers. At the time, Google had no public-facing developer documentation, and the style guide was for people creating internal documentation for Google engineers. It started out lightweight; the writers were leery of prescriptive guidance that might slow them down.
Over time, the writing team grew, and we began publishing public documentation for developers. Writers and editors didn’t want to make the same decisions over and over, so the writing groups made decisions, and these were recorded in the style guide. When we created a formal editorial team, that team took over ownership of the style guide.
These days, there are hundreds of technical writers, not to mention engineers, solutions architects, developer advocates, and others who write “external-facing” documentation. These writers consult (or are referred to) the style guide daily for answers to small and large questions.
In addition, many people are involved in open-source projects to which anyone can contribute, inside or outside Google. These projects require documentation that’s sometimes as extensive as that for commercial projects. As with open-source software itself, the documentation is created by volunteers.
A few years ago, we saw that the open-source community could benefit from the same guidance that our Google writers have. We therefore made the style guide public as a resource for people who are creating documentation for any software project.
The developer documentation style guide is not the only style guide at Google—different teams and different audiences have different needs. For example, there’s a style guide for creating user interfaces, one for our advertising tools, and another for support pages for our consumer products. But the developer style guide is probably the most widely used style guide at Google.
How it’s updated
Suggestions for additions or revisions to the style guide can come from anywhere—editors, writers, even programmers. The editorial team meets every Tuesday to review suggestions and sort out what to do about them. Decisions are made by consensus, sometimes involving some lively back-and-forth. We keep notes so we can revisit why we made a decision. (The notes go back to 2016 and run to nearly 500 pages.)
We publish changes continuously. To help people keep track of changes, the style guide includes a What’s new page that’s updated every week. As some of you might have seen, we also occasionally post about the style guide on social media.
Is this style guide for you?
Our style guide is primarily focused on developer documentation for Google products. But if you like the decisions we’ve made, you’re welcome to add our guide to your toolbox.
And if you have feedback—questions, corrections, ideas—we’d love to hear them! Click the Send feedback link that’s at the top of every page and tell us your thoughts.
Highlights
Voice and tone. Google voice aims to sound conversational, friendly, and respectful. As we advise, “try to sound like a knowledgeable friend who understands what the developer wants to do.”
Word list. The word list includes decisions we’ve made about how to spell, hyphenate, or sometimes avoid certain terms that come up frequently.
Product names. We provide guidance for how to use (and not use) Google names.
Write for a global audience. We recommend principles that make our documentation clear for people who don’t live in the US, for those who don’t speak English as a primary language, and for our translators. We believe that following these principles helps all our readers.
Write for accessibility. We provide guidelines for how to make the documentation available to people who might have any sort of restriction in how they consume the docs.
Write inclusively. We help writers create language that’s gender-neutral, that addresses a diverse audience, and that avoids offensive, triggering, and ableist language.
Reference hierarchy. We can’t capture a recommendation about every question a writer will have. Therefore, we also suggest other resources, like project-specific style sheets, the Merriam-Webster dictionary, The Chicago Manual of Style, and other industry style guides.
Breaking the rules. “This guide contains guidelines, not rules. Depart from it when doing so improves your content.”
This article was originally published in Tracking Changes (Spring 2021 edition). Members receive a PDF of the quarterly Tracking Changes newsletter by email.
Header photo by Hack Capital on Unsplash
