Google Publicly Releases Internal Developer Documentation Style Guide (betanews.com) 96
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.
Re: (Score:1)
Now we can all do just like google! It's all I've ever wanted!
What?
Strip-mine everyone's privacy and sell it off as many times as you can?
Why be merely evil when you can be so much worse!
Good engineers write good documentation (Score:5, Insightful)
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 (Score:2, Interesting)
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
Re: (Score:1)
Re: (Score:2)
When you're running an open source development effort, the developers you're trying to enlist are the target "end users" of your efforts.
Documentation is part of design and implementation (Score:5, Insightful)
"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: (Score:2)
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 poor
Re:Documentation is part of design and implementat (Score:5, Insightful)
"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."
Re: Documentation is part of design and implementa (Score:2)
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.
Re: (Score:2)
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.
Re: (Score:2)
Don't take it up with me, take it up with your dictionary.
Re: (Score:2)
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.
Re: (Score:2)
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.
Re: (Score:2)
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?"
Re: Good engineers write good documentation (Score:5, Insightful)
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.
Re: Good engineers write good documentation (Score:2)
I stand by my comment. Look at any of the studies discussing work breakdowns in serious software engineering projects: the amount that can be fairly called documentation will be less than the amount of other design work (thinking, analysis, experimentation, etc.) plus implementation, to say nothing about requirements development or verification or the other odds and ends of a development cycle. You wrote that "doing it right" meant that documentation takes a majority of the time, and that is simply wrong.
Re: (Score:2)
This allows for experiments, A-B testing, ongoing user/customer inputs and even sensible scope decreases/increases.
You aren't recording the results of those experiments, testing, and conversations? If not, then you're wasting your time and effort doing those things at all. If so, then you're creating documentation.
Re: (Score:2)
So here's the thing. I'm not going to tell you how to do your job, but I think you may be making a mistake in your assumptions here. Software devel
Re: (Score:2)
If something is documented properly then actually implementing it will generally take a minority of the time.
The waterfall delusion. That can just as easily lead to things taking longer and work being of poorer quality as the developer tries to mold reality to the "design".
Re: (Score:2)
The majority of documentation is not for the end user, it's for engineers working on the code.
Re:Good engineers write good documentation (Score:5, Insightful)
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: (Score:3)
I'm looking at you, Keith Packard and friends.
I've often wondered how much all of the X-replacement projects are addressing actual limitations in X11 and how many are simply unable to navigate the terse and undocumented X.org code.
Re: (Score:2)
Re: Good engineers write good documentation (Score:3, Interesting)
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 an
Re: (Score:2)
Good documentation in a well documented system is very valuable. Even a little outdated, false or misleading documentation is poison to that value because you just can't rely on it. And a few good pages in a pile of shit is almost worthless. If you're on a team with stupid, lazy or poor programmers or contractors / consultants / outsource staff that don't care much for long time maintainability or you've inherited a big codebase then most likely some or all of them has taken the easy way out. And you probab
Re: (Score:2)
Very often if you get a lot of questions about something it's because it's stupidly built and what it really needs is either a refactoring of the code or redesign of the UI or both.
And knowing how to do that often requires knowing why the application does what it does in the first place; that's something you can often only glean from documentation as whoever came up with the spec or wrote the damned thing in the first place is no longer with the company.
Re: (Score:2)
Computer engineering is not like any other kind of engineering that it's cool to just improvise as we go along. A colleague of mine describes our job as re-engineering the airplane while it's in the air.
This is often the case, but not because there's anything special about software engineering as opposed to other engineering (there isn't).
It's that way because too many software engineers have absolutely awful engineering habits, and topping the list is the documentation problem. Your colleague's comment highlights this problem -- if that's the way your job goes, then your engineering process is broken.
Re: (Score:2)
All that code inside, implementing that API? Waste of time. Good commenting + unit tests will be bett
Re: (Score:2)
Good commenting + unit tests will be better than any word doco.
Perhaps we're having a language problem here. In my view, good comments (which are unbelievably rare, in my experience) and unit tests are a form of documentation.
But neither of those are sufficient by themselves, because they're very close-up views. You also need documentation that is from a greater distance. Again, though, this doesn't have to be in form of word documents. Meeting notes, memos, email exchanges, etc. -- all of that is documentation.
Re: (Score:2)
I can imagine lots of situations where what you say is correct, but i've also come across (and mainly work) in situations where this would be totally over the top, and wasted effort.
As an example, i've written tonnes of software that is only ever used once - you know the stuff, the 'load this dataset into the database' type task which is basically a bit of scripting, takes an hour or two, is run once, and is then thrown away. It might not even make it into source control. How about those ad-hoc queries you
Re: (Score:2)
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.
And for themselves in the future. When you have to revisit code you wrote five years ago, it is effectively no different than if someone else wrote the code.
I've heard a lot of programmers make the claim that good code should be self documenting and while there is truth to that
There is truth to it, but the truth is limited. Well-written code tends to be self-documenting in the local sense -- you can look at a file and understand what is being done in that file. It does not tend to be self-documenting in the big-picture sense, and is not self-documenting at all when it comes to the "why": why was this engineering decision made
"Word choice" (Score:1)
"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 [vidarholen.net]
Re: (Score:2)
Please stop wasting pixels with this gibberish.
Re: (Score:2)
BetaNews is exercising a new paradigm: aspect-oriented reporting.
Re: (Score:2)
Dropping article. Annoys shit out of me.
Google Documentation (Score:4, Interesting)
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 ;-)
Re: (Score:2)
Serial Comma? (Score:5, Funny)
Re: (Score:2)
Google's external documentation is awful (Score:4, Insightful)
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.
Re: (Score:2)
void onDraw (Canvas canvas)
Implement this to do your drawing.
And big surprise, no mention in the style guide of updating documentation when something becomes deprecated.
Spaces! (Score:2)
Re: (Score:2)
Google has documentation? (Score:2)
In fact, does anybody have user documentation any more? At least, any that's slightly useful?
Punctuation Usage? Really? (Score:2)
Re: (Score:3)
Documentation is hard... (Score:2)
Now we know why projects are abandoned (Score:2)
Actual example you may want to read https://developers.google.com/... [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?... [youtube.com]
The bigger issue (Score:3)
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.
Mistake in nomenclature (Score:2)