Re:Technical Writing Courses from Google
by danesparza on Monday August 08, 2022 @03:57PM
(#32390274)
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.
[ Parent
| on HN ]
Re:Technical Writing Courses from Google
by edmundsauto on Monday August 08, 2022 @04:29PM
(#32390604)
I 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.
Re:Technical Writing Courses from Google
by maxerickson on Monday August 08, 2022 @06:08PM
(#32391734)
It'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
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
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.
Re:Technical Writing Courses from Google
by joshuamorton on Monday August 08, 2022 @06:39PM
(#32392022)
The 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.
Re:Technical Writing Courses from Google
by danesparza on Tuesday August 09, 2022 @01:16PM
(#32400806)
I'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?
Dart's documentation is comprehensive, well-written, and provides tons of meaningful examples.[0].
I've found the GCP documents well-written and nicely structured, at least around cloud storage and pubsub.
Re:Technical Writing Courses from Google
by MonkeyMalarky on Monday August 08, 2022 @05:47PM
(#32391511)
I 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.
Angular docs are pretty good. Also didn't have trouble with GCP docs.
Re:Technical Writing Courses from Google
by clumsysmurf on Monday August 08, 2022 @05:47PM
(#32391501)
Speaking 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!)
Android'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.
True. 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.
Re:Technical Writing Courses from Google
by bencorman on Monday August 08, 2022 @06:05PM
(#32391705)
Flutter's documentation is fantastic. A lot of effort went into it, and it shows.
Far as their public stuff goes, I'd tend to agree with you. If the OpenBSD folks published a course like this, though...