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.
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.
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.