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.
Now we can all do just like google! It's all I've ever wanted!
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.
Step one: make sure your docs are at least a major release behind your software.
"you now have direct access to useful guidance about voice, tone, word choice, and other style considerations"
Word choice? I'm guessing 'fucking' is ruled out then. Poor old linus excluded again.
Swear words are almost a staple of writing code as shown in this nice graph: https://www.vidarholen.net/contents/wordcount/old.html
LOL. How about grey text on a white background. Or grey text on a grey background - it's SO original! But it's the law! (Apparently, judging from just about every website and even PC programs nowadays...)
It was Google that invented 'Material Design', which translates to 'Atrociously bad user interface design', but they are 'the law' and have to be blindly copied by so-called 'designers', apparently.
Step two: Give up writing halfway with a note that you got bored and you may continue "later". Now half the ToC points into limbo. Never ever update anything afterwards. Not now, not next week, not ten years down the road. (*cough* a certain popular irc client *cough*)
Seems to me that this documentation document is itself so long that it would benefit from having a tool that helps 'enforce' the policy like Grammarly or something.
>> Unfortunately, many developers aren't very interested in documentation aspect, so it often gets neglected.
What is "documentation aspect"? Is this a compound noun? Is it ironic that a post about documentation uses a sentence that does not conform with the rules of the language in which it is written?
"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.
This is one of the problems: sloppy commenters like to read ideas into statements that contradict those ideas.
Creating documentation is sharply distinct from design and implementation. It requires a different skill set and attitude, although it must be done in harmony with the rest of the development effort. I did not suggest it was not important. I only pointed out that it is different, and explained why developers should spend most of their time on things besides documentation.
Something that works poorly will not work any better just because it comes with great documentation, and people tend to think that "lots of documentation" is automatically "good documentation"; see also the well-deserved comments in this thread about explanation-free Doxygen output.
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 ;-)
I converted all my serial commas to USB long ago. If I need one I can always use a virtual serial comma.
Support Right To Repair Legislation.
"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."
Again, I said documentation is distinct from those other things, not that it was optional. You're continuing to misread plain English. You recognize that someone might design or create a thing without documenting what they did. That means the documentation is distinct. We agree that the documentation still needs to be done.
"Code is self-documenting"
No, it's not.
No section on gender-neutral language. That offends me.
I personally wouldn't look to Google for style tips. They may be good at a number of things, but style is not one of them. Kudos to them for trying, though.
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.
It's official. Google published it and they are always right. Spaces are better than tabs! :P
We'll make great pets
I can't wait to see what wisdom comes from the place that disallows unsigned ints!
It's nice to see that the Anglophone world is moving away from Capitalizing Every Single Word. But why is the document that prescribes sentence case for document titles named "Google Developer Documentation Style Guide"?
In fact, does anybody have user documentation any more? At least, any that's slightly useful?
It's a pretty sad state of affairs when a style guide aimed at adults has to include direction on correct punctuation. Is the standard of written English that low at Google? I suppose it could be aimed at non-English users but even so...
I had a dream, bright and carefree, but now there's doubt and gravity
The problem with the notion that documentation is inline with coding is that you create worthless documentation that way. Procedure-level isn't all that important. If your code is readable, most of the time you can see right away what it does. That kind of documentation and even more so instruction-level documentation is only necessary in particularly complex code. Often sorely missing though is design-level documentation that is up-to-date. How parts interact with each other is much more difficult to see from reading code. If you don't treat documentation as a separate task, you'll write lots of unneeded documentation and hardly any essential documentation.
As a layman programmer, I find it easier to write good code than to write good unit tests than to write good documentation.
Now that my company has converted to Agile Scrum, we have learned that documentation is waste. I read a lot of comments talking about "design", "implementation", and "documentation." Those are Waterful terminology and Waterful is bad! No good software was ever written that way.
With Scrum, you don't need documentation. We demo every two weeks. If the customer says it looks good, we kick it out the door.
It really depends what you mean by self-documenting. If you limit it to documenting what or how, it absolutely is. However, when you consider the more important why factor, you're right, that documentation also needs to exist; sometimes even more important is who and when, and you should be thankful if you find yourself still able to disagree with that.
APK quotes people (including myself) without context and should not be trusted. Just thought you should know.
I usually start creating good documentation the moment my project manager is not pushing for other features to be implemented and tested ASAP because time and money and project budget and delivery!!!
Which is about 10% of the time.
Google's documentation is terrible.
I know there are tons of fanboys who love everything Google does, but Google's documentation is simply bad. Sure, they have a lot of words, and it's formatted, but the content is virtually useless. They spend pages and pages describing basic computer science concepts, and they write something for every obscure parameter and function, but they completely omit the basic usage information that people read documentation to find!
Try this experiment: Go read the Kubernetes documentation, and try to find a simple description of what you need to put into a YAML file in order to push a docker image to a cluster and expose it as an HTTP(S) service. You are not allowed to copy somebody else's configuration file, you have to generate it solely using the documentation.
Go ahead, try to do it. You will fail.
Google's documentation is written for the non-existent audience of people who are intimately familiar with how Google's internal systems work, but somehow lack a basic understanding of computer science fundamentals. It is not useful. It is simply bloviated words on a page.
another thing is sometimes the "other" person is you down the road
SlashDot Mini Poll:
Number of times y'all as a programmer has said "what was i drinking/smoking when i did this?"
The grammar nazis take over and Google spends all their time making sure 'that' is the correct place . .
Actual example you may want to read https://developers.google.com/...
The API picker lists the most common things you may want to do. (Bad)
The API picker lists the most common things that you may want to do.(Good)
College Humor video , Grammar is very important to Google https://www.youtube.com/watch?...
The bigger issue is just getting developers to write documentation in the first place. That's a situation that's gotten even worse with the rise of "agile" methodologies.
Creating documentation is sharply distinct from design and implementation.
I couldn't disagree more. Creating documentation is part of design and implementation, not something distinct from it.
I start creating documentation the moment that I'm being given specifications for the project. I call them "notes", but they're also critical documentation that is as important to the project as source code.
Don't take it up with me, take it up with your dictionary.
Especially in the software world, there is the notion that everything that is not programming is documentation. What is not recognised is that a whole lot of this documentation is plans: requirements are a plan, for testing you need a plan, architecture is a plan. Meeting notes and reports act as version control information on the plans, to record on how the plans changed, on what the ideas are behind the plans. Design of electric and electronic circuits, mechanical engineering, building all needs plans. Consider that in software engineering a real part of so called documentation are actually plans needed to provide a overview of what needs to be implemented.
a javadoc (or similar) dump of class methods, members, etc is NOT DOCUMENTATION and is not useful to tell you how to use something