Slashdot Mirror

← Back to Stories (view on slashdot.org)

Google Publicly Releases Internal Developer Documentation Style Guide (betanews.com)

Posted by BeauHD on from the free-for-all dept.

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.

50 of 96 comments (clear)

  1. Good engineers write good documentation by sjbe · · 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.

    1. Re: Good engineers write good documentation by Entrope · · Score: 1, 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. If it is, you're designing something that is too hard to use.

    2. Re:Good engineers write good documentation by TheRaven64 · · Score: 4, 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.

      --
      I am TheRaven on Soylent News
    3. Re:Good engineers write good documentation by TheRaven64 · · Score: 2

      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.

      --
      I am TheRaven on Soylent News
    4. Re: Good engineers write good documentation by Entrope · · Score: 1

      When you're running an open source development effort, the developers you're trying to enlist are the target "end users" of your efforts.

    5. Re: Good engineers write good documentation by Anonymous Coward · · 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 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.

    6. Re: Good engineers write good documentation by sjbe · · Score: 4, 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.

    7. Re: Good engineers write good documentation by Entrope · · Score: 1

      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.

    8. Re: Good engineers write good documentation by Gr8Apes · · Score: 1

      Depends upon what you're telling them to do. Take the Beagle 2 for instance, they didn't do enough documentation telling people what to do.

      --
      The cesspool just got a check and balance.
    9. Re:Good engineers write good documentation by Kjella · · Score: 1

      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 probably haven't got management buy-in to really enforce anything and you don't want to be the documentation nazi either.

      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. I don't write much documentation because I don't read much documentation, most of it is dog poop and it's usually more efficient to just dive into the code and figure out WTF it's really doing. And very often there's a long TODO-list of things that ought to be done, where I seem to make the most people happy - both users, other developers and my boss - by whack-a-mole'ing as many as possible as quickly as possible.

      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. It's extremely rare that I end up thinking this is how it should be or has to be, they only need a better explanation of it. As in, I find the solution to 90% of the issues is to write more code or better code. Documenting a convoluted mess sometimes only makes it a documented, convoluted mess. That said, I try to cover every error path and throw useful error messages. The worst I get are things that just silently fail or corrupt or just give gibberish in return. There's enough coders who can't even do that.

      --
      Live today, because you never know what tomorrow brings
    10. Re:Good engineers write good documentation by Puff_Of_Hot_Air · · Score: 1
      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 better than any word doco. In-fact, providing a little stripped to the bones demo app, implementing each api call (with a little comment around each piece), that is built as part of your project, is better than a pdf any day of the week.

      Generally though, documentation is all about who you are communicating with. Co-located team members? Waste of time. Distributed geo-location teams? Make sure the boundaries are very well documented. Selling something to be consumed externally? Document, provide examples, provide demos. Mostly it's just common sense.

    11. Re:Good engineers write good documentation by BronsCon · · Score: 1

      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.

      --
      APK quotes people (including myself) without context and should not be trusted. Just thought you should know.
    12. Re: Good engineers write good documentation by Puff_Of_Hot_Air · · Score: 1
      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 development is fundamentally different from the traditional engineering with which you would be familiar. I know this because I have done both.

      If something is documented properly then actually implementing it will generally take a minority of the time.

      Completely false. I have worked in both heavy and light documentation environments. Heavy waterfall style process as well as agile. The implementation is always the longest leg.

      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.

      Do you count the code you use to help run your plant? If you use PLCs or SCADA, have you thought about the companies that make that software? Chances are that I know, work with, or am the person who wrote that code. The kind of process that you are familiar with that happens inside your plant does not happen with the software on which you run your software! And it's not going to be consistent across the board from the one company either. What's required for the PLC, documentation wise, is very different from what is required in the SCADA.

      The notion that you can do non-trivial tasks without having substantial proper documentation is just absurd.

      My experience would suggest otherwise, its a funny old world.

    13. Re:Good engineers write good documentation by Cesare+Ferrari · · Score: 1

      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 produce to answer a management query - 'what sort of data rates have we had to deal with historically' or whatever.

      How about your bash profile? You got any documentation for it? Those helper scripts to wrap some confusing build/test cycle commands that you need?

      So I would be careful with any catch-all thinking about documentation, certainly in the software field. I've dealt with various supplied APIs from external suppliers with excellent documentation, and i'm currently working with one with horrendous documentation, and I know which i'd rather have!

    14. Re:Good engineers write good documentation by JohnFen · · Score: 1

      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 the way it was? What was the tradeoff here? What were the risk assumption? Etc. Those questions can become crucial to have answers to, and the answers are often opaque even in the best-written code.

      On the other hand, there is something worse than no documentation: misleading documentation.

      Good engineers write good documentation.

      This is 100% correct. If you write stellar code but terrible (or no) documentation, you are not being a good engineer. You are being a code jockey.

    15. Re: Good engineers write good documentation by JohnFen · · Score: 1

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

    16. Re: Good engineers write good documentation by JohnFen · · Score: 1

      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.

    17. Re:Good engineers write good documentation by JohnFen · · Score: 1

      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.

    18. Re:Good engineers write good documentation by JohnFen · · Score: 1

      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.

    19. Re: Good engineers write good documentation by Kielistic · · Score: 1

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

  2. "Word choice" by Anonymous Coward · · 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

  3. Re:Salvation by Anonymous Coward · · 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!

  4. Documentation is part of design and implementation by mveloso · · Score: 4, 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.

  5. Re:Documentation is part of design and implementat by Entrope · · Score: 1

    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.

  6. Re:Documentation aspect. by Entrope · · Score: 1

    BetaNews is exercising a new paradigm: aspect-oriented reporting.

  7. Google Documentation by coofercat · · Score: 3, 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 ;-)

    1. Re:Google Documentation by Graydyn+Young · · Score: 1

      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.

  8. Serial Comma? by Comboman · · Score: 4, Funny

    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.
  9. Re:Documentation is part of design and implementat by mveloso · · 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."

  10. Re: Documentation is part of design and implementa by Entrope · · Score: 1

    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.

  11. Google's external documentation is awful by peppepz · · Score: 3, Insightful
    ...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.

    1. Re:Google's external documentation is awful by Graydyn+Young · · Score: 1
      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.

  12. Re:Gender-neutral language by peppepz · · Score: 1

    Are you sure? https://developers.google.com/...

  13. Spaces! by zifn4b · · Score: 1

    It's official. Google published it and they are always right. Spaces are better than tabs! :P

    --
    We'll make great pets
    1. Re:Spaces! by cdreimer · · Score: 1

      I heard that Google uses two spaces rather four spaces for Python code.

  14. Google has documentation? by Chris+Mattern · · Score: 1

    In fact, does anybody have user documentation any more? At least, any that's slightly useful?

  15. Punctuation Usage? Really? by Oxygen99 · · Score: 1

    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
    1. Re:Punctuation Usage? Really? by cdreimer · · Score: 2

      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.

  16. Documentation is hard... by cdreimer · · Score: 1

    As a layman programmer, I find it easier to write good code than to write good unit tests than to write good documentation.

  17. Re:Documentation aspect. by Hognoxious · · Score: 1

    Dropping article. Annoys shit out of me.

    --
    Confucius say, "Find worm in apple - bad. Find half a worm - worse."
  18. Re:"B-but code is self-documenting" drooled the id by BronsCon · · Score: 1

    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.
  19. Re:Is grey text compulsory too? by spacepimp · · Score: 1

    Please stop wasting pixels with this gibberish.

  20. Re:Documentation is part of design and implementat by allcoolnameswheretak · · Score: 1

    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.

  21. Re:Documentation is part of design and implementat by laurencetux · · Score: 1

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

  22. Now we know why projects are abandoned by bongey · · Score: 1

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

  23. The bigger issue by JohnFen · · Score: 2

    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.

  24. Re:Documentation is part of design and implementat by JohnFen · · Score: 1

    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.

  25. Re:Documentation is part of design and implementat by JohnFen · · Score: 1

    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.

  26. Re:Documentation is part of design and implementat by Entrope · · Score: 1

    Don't take it up with me, take it up with your dictionary.

  27. Mistake in nomenclature by chthon · · Score: 1

    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.