Please create an account to participate in the Slashdot moderation system

 



Forgot your password?
typodupeerror
Google Software The Internet Technology

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.

Google Publicly Releases Internal Developer Documentation Style Guide

Comments Filter:
  • by sjbe ( 173966 ) on Tuesday September 12, 2017 @06:41AM (#55179585)

    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.

    • 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

      • by mveloso ( 325617 ) on Tuesday September 12, 2017 @07:28AM (#55179721)

        "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.

        • by Entrope ( 68843 )

          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

          • by mveloso ( 325617 ) on Tuesday September 12, 2017 @08:02AM (#55179857)

            "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.

          • 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 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.

          • 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.

        • 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?"

      • by sjbe ( 173966 ) on Tuesday September 12, 2017 @08:49AM (#55180029)

        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.

        • 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.

        • I notice in a previous post you have written, that your day job is running a manufacturing plant. Well my day job is leading the technical group (development group) for the software products that you more than likely use to help you run your plant. I know what engineering is, because I used to be one, many of my friends are engineers, and my users are engineers.

          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

        • 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".

      • The majority of documentation is not for the end user, it's for engineers working on the code.

    • by TheRaven64 ( 641858 ) on Tuesday September 12, 2017 @07:03AM (#55179641) Journal

      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.

    • by Anonymous Coward

      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

    • by Kjella ( 173770 )

      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

      • 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.

      • 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.

    • There are times for documentation and times for no documentation. As so many on slashdot are fond of pointing out "Software Developers are not Engineers". Having been an engineer that changed careers 15 years back, I know that to be very true (although the implied superiority in this statement is unwarranted). Creating an API that is intended to be consumed outside of your direct team? Document that sucker.

      All that code inside, implementing that API? Waste of time. Good commenting + unit tests will be bett

      • 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.

    • 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

    • 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

  • by Anonymous Coward

    "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]

  • Google Documentation (Score:4, Interesting)

    by coofercat ( 719737 ) on Tuesday September 12, 2017 @07:57AM (#55179833) Homepage Journal

    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 ;-)

    • For a REST API these days documentation has gotten very easy due to the Open API standard. For most major frameworks you don't even need to write any sort of definitions, you just put annotations in your code. Then run it through Swagger UI (or similar) and it generates standardized, informative, and even interactive documentation. It's really beautiful.
  • by Comboman ( 895500 ) on Tuesday September 12, 2017 @07:58AM (#55179839)
    I converted all my serial commas to USB long ago. If I need one I can always use a virtual serial comma.
  • by peppepz ( 1311345 ) on Tuesday September 12, 2017 @09:05AM (#55180095)
    ...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.

    • Oh, my personal favourite Android documentation is for View's onDraw method:

      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.

  • It's official. Google published it and they are always right. Spaces are better than tabs! :P
  • 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...
    • The style guide notes that documentation will probably be read by people who speak English as a second language and/or translated into a foreign language. It make sense to simplify the usage of English to make reading and translating easier for non-English speakers. Documentation isn't literature.
  • As a layman programmer, I find it easier to write good code than to write good unit tests than to write good documentation.
  • 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/... [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]
  • by JohnFen ( 1641097 ) on Tuesday September 12, 2017 @04:38PM (#55183635)

    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.

  • 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.

"No matter where you go, there you are..." -- Buckaroo Banzai

Working...