The good news is that Google has released the Google Developer Documentation Style Guide . The bad news could soon be that Google released the Google Developer Documentation Style Guide .
It doesn’t have to be that way.
I’m delighted to see that the style guide includes, albeit below the fold, the advice to:
Remember that everything in this guide is a guideline, not a draconian rule.
Personally, I think this caveat should be on every page as part of the chrome, but at least it’s in the introduction. Unfortunately, my cursory review of the guide shows that the rules provide little context to help readers (in and out of Google) decide when would be good time to break a given rule and what the consequence or effect of that might be. But, this is not new. It has been a deficiency in technical communication guidelines and best practices that I’ve complained about for several years now. Maybe in v2?
Getting started
The highlights are a good place to start and provide a short cheat sheet of rules that are relatively universal and, while they don’t provide any resources or background for why these are good practices, I’m familiar with research that supports most of the suggestions, but I’m an outlier.
Hey, Google editors, for v2, please provide links to the background and research behind these guidelines to help readers–that is, the technical writers who will be applying these principles–understand why these are good practices and when they might want to make exceptions as you suggest in the opening caveat.
The language and style guidelines are worth a read to help make your content easy to read and understand by making it consistent–and not just within Google documentation, but these guidelines also closely follow other style guides.
Because I have no problem with the general principles at the headline level, I skipped down to my more favorite topic of API Reference topics (like I said above, I’m an outlier).
Where you should break a rule
So, right off the bat, on the API Reference Code Comments page, I think a more nuanced approach is worth considering. The first sentence of this page declares:
When you’re documenting an API, provide a complete API reference, typically generated from source code using doc comments that describe all public classes, methods, constants, and other members.
Which brings to mind the endless pages of Javadocs documentation that present a microscopic view of the picture, and which typically live at the wrong end of the usability scale for many use cases. Don’t get me wrong. I’m not saying that detailed documentation is not useful, but, at scale it tends to become unusable and very costly to keep up–something to consider when building a new API, by the way.
Where I think some rules were made to be broken starts with their Documentation Basics section of that page where they say, first and foremost, that:
The API reference must provide a description for each of the following:
- Every class, interface, struct, and any other similar member of the API (such as union types in C++).
- Every constant, field, enum, typedef, etc.
- Every method, with a description for each parameter, the return value, and any exceptions thrown.
To which I agree in principle, but not in the way that it sounds.
Taken at face value (and as they describe in the text that follows this proclamation), this results in a lot of pages with a lot of redundant content. Such a rule is easy to enforce on the production side by having automated processes scan the content and produce defect lists of discrepancies, but consider what it looks like to the reader. (PLEASE! Consider this before you decide this is a good idea).
Taken to its logical extreme, you can end up with hundreds, or in the case of some large companies, hundreds of thousands of topics that share a large percentage of the same content on every page! While this makes for a complete documentation set, the effectiveness of the content is quickly muted as the boilerplate content makes readers’ eyes glaze over. (Boilerplate content has been noted as unhelpful in several studies of API reference topics, by the way).
Reading further into the documentation linked from this topic, you can see how this starts to get tedious as you scroll down to see documentation that is complete but annoying. Methods such as:
ActionBar.SetTitle Sets the action bar title
ActionBar.SetSubtitle Sets the action bar subtitle
Why?
How do you avoid this redundancy without losing documentation fidelity? Easy.
Conventions and consistency
You can save a lot of redundancy in documentation (and add a lot of usability to both the API and its documentation) by adopting and adhering to conventions. This has to start during the design phase, but if you have an API that applies conventions consistently, such as through naming, parameter and variable typing, and return values), you can minimize a lot of content by saying, in effect, “it does what you would expect it to do.”
If the method does what it says it does, how many times do you need to say that for a developer to get the point? (Once, is what the research says, BTW) I realize that this practice likely came about when documenting code that might not do what it says it would. I’m pretty sure we can all agree, nowadays, that such code is just broken and should not try to be fixed by a documentation bandage. Just remember these two points:
- You can’t fix bad design with bad documentation
- You can’t fix bad design with good documentation, either (in case you were wondering).
Overall
I’m glad to see that this resource is easily and freely accessible (unlike the last Microsoft Manual of Style for Technical Publications (4th Ed.) that I had to pay for–and it didn’t even include much about API docs). I would encourage people to follow it insofar as it makes sense (and only you know how far that is). From what I’ve studied, the guidelines I reviewed, with the exception of my short API doc rant, are sound and can be traced back to (or have been confirmed by) research.
Looking forward to v2 and the links to the supporting references!