Documentation is often an afterthought — especially for open-source projects. That can make it harder for newcomers to join a project, for example, and sometimes badly written documentation is worse than having no documentation at all. To help developers write better documentation, Google this week opened up its own developer-documentation style guide.
This is the same style guide Google uses internally for writing the documentation of its own projects like Kubernetes and Dart.
The guide itself includes everything from a word list to ensure the consistent spelling of our industry jargon (it’s “data center,” not “datacenter,” for example), how to use hyphens (and when not to), why you should use active voice and other basics. What developers may care more about, though, is that the guide also talks about how to write good API code comments and how to best document command-line syntax.
Other companies, including Atlassian, WordPress and Salesforce, have also made their style guides public, though few are quite as in-depth as Google’s, especially when it comes to the basics.
The team behind the style guide notes that this is a living document and it will change over time. It also stressed that this is just one way of doing things — and in a world where the proponents of the MLA guide still regularly get into fistfights with the Chicago-style faction and fans of the AP Stylebook (which we kind of follow here at TC), that’s a good thing to keep in mind.
