4 ms·
Normally, I love free resources like this. I don't mean to throw shade at Google... but can anybody tell me if there is a set of documentation that Google has
by danesparza 4y ago
Normally, I love free resources like this. I don't mean to throw shade at Google... but can anybody tell me if there is a set of documentation that Google has created that you would hold up as a standard that you would personally like to match? I can't think of anything. I really think Google needs to get a lot better at documentation before they start passing out classes like this.
- edmundsauto 4y agoI disagree - the advice can be top notch independent of Google's organization successes. Teaching individuals still has value, because nobody is born a great writer. Google's failure could be because the org is not incentivizing good documentation.
- deleted 4y ago[deleted]
- maxerickson 4y agoIt's got issues. Like the use of the word "develop" for the clear and short sentence strategies on this page: https://developers.google.com/tech-writing/one https://developers.google.com/tech-writing/one Utilize and employ are about the same level of obscurity as 'develop' and much closer to the intended meaning. A later inspirational message is very impressed with itself: https://developers.google.com/tech-writing/one/paragraphs https://developers.google.com/tech-writing/one/paragraphs The work of technical writing is to organize and clearly present information. I wouldn't pat myself on the back if I published a writing guide that was easy to nit pick.
- joshuamorton 4y agoThe goal of something and the work of something are distinct. Untangling a topic is work done in service of, ultimately, clearly presenting information. The guide appears correct, and your criticism misplaced.
- danesparza 4y agoI'll take it. Thank you. My question still stands: What is a body of documentation that Google has completed that you would hold up as a standard of work worthy of imitation?
- User23 4y agoThe Go documentation is high quality.
- ColanR 4y agoFar as their public stuff goes, I'd tend to agree with you. If the OpenBSD folks published a course like this, though...
- rickette 4y agoAngular docs are pretty good. Also didn't have trouble with GCP docs.
- gresrun 4y agoDart's documentation is comprehensive, well-written, and provides tons of meaningful examples.[0]. [0]: https://dart.dev/guides https://dart.dev/guides
- gundmc 4y agoI've found the GCP documents well-written and nicely structured, at least around cloud storage and pubsub.
- MonkeyMalarky 4y agoI find GCP documentation to be very bipolar. It's either spartan and terse, or almost overwhelmingly too much. In the latter category, sometimes it's like the getting started article for one topic links to more and more until all of a sudden you've got 20 tabs open.
- clumsysmurf 4y agoSpeaking for Android, the guides are pretty good, but the references from javadoc are abysmal. I wonder how much of this is because of scaling flaws in javadoc tooling for usage over such a large code base. But, in some cases, its clear because there are no javadocs at all (can't blame the tools for that!)
- trebbble 4y agoAndroid's developer docs are the only ones from Google I've used extensively enough to have an opinion on them, and that not in the last three years or so, but those spent at least a decade being notably poor.
- cudgy 4y agoTrue. Given how Google’s Android platform provides numerous ways to accomplish the same task and deprecates APIs on a bi-yearly basis, the documentation provides little guidance on whether what you are currently reading is deprecated and what methods to accomplish the task should be used. Good luck finding any explanation as to why the deprecations were made in the first place.
- bencorman 4y agoFlutter's documentation is fantastic. A lot of effort went into it, and it shows.