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.

Comments

Good engineers write good documentation

[sjbe]

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.

That's putting it mildly. For any kind of engineer documentation is crucial and when you are Doing It Right actually accounts for the majority of the job. An engineer's job is to figure out a plan to solve a problem AND then to generate documentation informing/instructing other people in the clearest possible way what to do to execute that plan. The documentation actually accounts for the majority of the work in most cases and is every bit as important as the solution because if you cannot communicate your solution then it is useless. Far too many engineers do documentation really poorly, and I'm not just talking about programmers. When they can be bothered they tend to forget that the documentation isn't for themselves - it's so other people can readily understand their solution to a problem and execute that solution reliably. I receive product drawings all the time that are missing critical details, fail to convey expectations, are written in a confusing manner, or are obviously reminder notes rather than instructions. Engineering is a team sport and communication and documentation are how the team collaborates.

I've heard a lot of programmers make the claim that good code should be self documenting and while there is truth to that, most of the time it's just an excuse to blow off the humdrum work of doing proper documentation fully. Code should be clear but documentation needs to make it even more so. Expecting your solution to be obvious and complete in every detail is a false economy. You are saving your time at someone else's expense. Good engineers write good documentation. If your documentation sucks then you are bad at engineering no matter how elegant your technical solution might be.

Re:Good engineers write good documentation

[TheRaven64]

I've heard a lot of programmers make the claim that good code should be self documenting and while there is truth to that, most of the time it's just an excuse to blow off the humdrum work of doing proper documentation fully.

This idea was the core of Knuth's Literate Programming model, where the code was embedded in the documentation and could be extracted and turned into something to feed into a compiler. The closest thing in widespread use is Doxygen, which is pretty poor in comparison to WEB, but a lot better than nothing.

Re: Good engineers write good documentation

[sjbe]

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.

You have that backwards and you seem confused about my point. If something is documented properly then actually implementing it will generally take a minority of the time. Design and documentation go hand in hand - one can not exist without the other. Code can be a form of documentation but the most reliable software out there spends a LOT of time on documentation that is not code. This has nothing inherently to do with safety. Most software "engineering" is in reality badly lacking in process and the results show it. I'm not talking about writing the user manual (though that's important too) but rather the actual documentation that goes with making a product.

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.

Two points. A) Not all engineering is software. Stop looking at documentation through such a narrow lens. B) You completely missed my point. I'm not talking about the design of the solution or end users. I'm talking about documentation written by engineers primarily for other engineers or other individuals tasked with carrying out the solution. Furthermore if you do want to talk about user documentation, most of that sucks too. The notion that you can do non-trivial tasks without having substantial proper documentation is just absurd. Yes good design minimizes the need for it but to pretend that you can dispense with all documentation because you have delusions that your design is so elegant it doesn't need it.

Documentation is part of design and implementation

[mveloso]

"If you're spending more time on documentation than on design or implementation "

This is one of the problems: engineers see documentation as "something else." Documentation is part of your deliverable, not something extra that you're forced to write because some moron in another department can't figure it out.

Your documentation allows other people to (1) understand what your code was supposed to be doing, and (2) how what you were doing fits (or doesn't fit) in with the overall project's requirements, and (3) how they're supposed to use your code. That's at a minimum. Ideally it should explain why you did what you did.

Not providing documentation wastes other people's time. If you don't understand your stuff well enough to document it, you shouldn't be writing the code.

Re:Documentation is part of design and implementat

[mveloso]

"This is one of the problems: sloppy commenters like to read ideas into statements that contradict those ideas."

No.

"Creating documentation is sharply distinct from design and implementation"

Uh, no. We can agree to disagree, but documentation on your code in my company is a deliverable. Code with no associated documentation is rejected. Developers who refuse to write documentation aren't hired.

"Something that works poorly will not work any better just because it comes with great documentation"

No, but it will allow someone else to figure out how you fucked up because your thinking is wrong. It will help the next person change the code because they will understand what you were trying to do so they can take your design and run with it.

Code only tells you what, but for any code that's useful the "why" is more important than "what."

Google's external documentation is awful

[peppepz]

...so I think they have very little to teach in that respect.

Moreover, what they are publishing is merely a style guide, and has nothing to with the fact that “many developers aren’t very interested in documentation aspect”. It is only useful to make the documentation from third-party contributors look like the one that Google have written themselves. It won’t help with the technical quality of anyone’s else documentation.