Slashdot Mirror
Google Publicly Releases Internal Developer Documentation Style Guide (betanews.com)
BrianFagioli shares a report from BetaNews: The documentation aspect of any project is very important, as it can help people to both understand it and track changes. Unfortunately, many developers aren't very interested in documentation aspect, so it often gets neglected. Luckily, if you want to maintain proper documentation and stay organized, today, Google is releasing its internal developer documentation style guide. This can quite literally guide your documentation, giving you a great starting point and keeping things consistent.
Jed Hartman, Technical Writer, Google says, "For some years now, our technical writers at Google have used an internal-only editorial style guide for most of our developer documentation. In order to better support external contributors to our open source projects, such as Kubernetes, AMP, or Dart, and to allow for more consistency across developer documentation, we're now making that style guide public. If you contribute documentation to projects like those, you now have direct access to useful guidance about voice, tone, word choice, and other style considerations. It can be useful for general issues, like reminders to use second person, present tense, active voice, and the serial comma; it can also be great for checking very specific issues, like whether to write 'app' or 'application' when you want to be consistent with the Google Developers style." You can access Google's style guide here.
Jed Hartman, Technical Writer, Google says, "For some years now, our technical writers at Google have used an internal-only editorial style guide for most of our developer documentation. In order to better support external contributors to our open source projects, such as Kubernetes, AMP, or Dart, and to allow for more consistency across developer documentation, we're now making that style guide public. If you contribute documentation to projects like those, you now have direct access to useful guidance about voice, tone, word choice, and other style considerations. It can be useful for general issues, like reminders to use second person, present tense, active voice, and the serial comma; it can also be great for checking very specific issues, like whether to write 'app' or 'application' when you want to be consistent with the Google Developers style." You can access Google's style guide here.
If you're spending more time on documentation than on design or implementation, you're either doing safety-critical work, or you're doing it wrong. 95% of software should use design elements that are familiar to the users in a way that makes it easy to discover how to do what they want.
There will always be uncommon tasks or unusual users such that some documentation is necessary (and that needs to be clear and effective), but end-user documentation should never be that big a chunk of the development effort. If it is, you're designing something that is too hard to use.
Anything to promote documentation, is, in my opinion a good thing. I once documented a simple REST API - I looked for a good style guide, or even some good examples of what to document and in what detail - I really found nothing especially useful. Even finding good examples of documentation on other APIs was pretty hard.
That said, if you've ever read any Google documentation, you'll know that a lot of it is really pretty confusing. There's never a summary, it talks about lots of steps you probably should do, but not right now as you're just trying to get the thing to work and just want to learn it. In short, it's not especially productive. So in that sense, I'm not sure if this is a guide you should follow or not ;-)
The problem I have with documentation is that it rarely maps onto the running state of the system. Granted I look at more technical docs than user docs but every aspect of the system gets skewed by hacking, retrofitting or just plain political struggle. Today's design is tomorrow's change of leadership.
Not even the code forms a consistent model, the tech docs don't mirror that code and the user docs look like they're talking about a different project entirely. The difference is that the code is a product and does something (sometimes) "useful".
And that's why programmers don't like docs.
And yes, working inside Google teaches you some things. One lesson is to look for the word "deprecated" and check timestamps on any Google Doc. Much of their technology runs on tribal knowledge because it changes daily.