12 ms·
Technical Writing Courses from Google
- _the_inflator 4y agoThis is great stuff. Resemblance with academia and academic writing is recognizable. However, I would have expected more tools to guide the process. NLP tools instead of writing exercises here and there.
- itake 4y agoDid you take the course? I saw on an HN thread mixed reviews.
- danesparza 4y agoNormally, 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.
- kinow 4y agoI am updatijg the user guide for an open source project, and found these short courses really helpful. It helps you write concisely and to keep the content simple. As well as provide some tools for structuring your docs. The other resources I used were Diatáxis [1] and writing books I had on my bookshelf (Stephen King, Zinsser, etc) [1] https://diataxis.fr/ https://diataxis.fr/
- CraigJPerry 4y agoA while back i took both modules, they don’t take long to go through. Module 1 wasn’t any value to me, it felt far far too basic, i was really caught off guard by how basic it is. Module 2 was ok-ish. The lasting change these courses left in me was more appreciation for investing time and effort into illustrations. I found other resources to be more impactful for me personally (e.g. jacobian / i’d rather be writing). I liked this model https://documentation.divio.com/ https://documentation.divio.com/ - agreeing with people what purpose the docs they’re writing are for is a big chunk of the problem surface area. Having a model makes life easier. I’m not sure it has to be this exact model but this one seems good enough to me. A counterproductive tendency I’ve observed frequently is when an SME is tasked with documenting their thing and they go off in ELI5 mode. So tutorial instead of how-to per the above model. Having that model helps keep those conversations short and productive.
- more_corn 4y agoHa! Google is the absolute worst entity to teach technical writing. Go read some of the documentation for google cloud. Pick any single thing you might need to do to stand up a new service. I guarantee you’ll be disappointed.
- 6ue7nNMEEbHcM 4y agoOr you could just take a look at the linked course and learn something. It's pretty good and worth working through.
- arccy 4y agoI find cloud documentation to be pretty clear most of the time
- mikedouglas 4y agoI've heard Google uses design docs pretty extensively for internal projects. Does anyone have a publicly shared example?
- ruuda 4y agoThere are many public ones on chromium-dev and blink-dev, e.g. https://docs.google.com/document/d/1OjZoHNvn_vz6bhyww68B_KZBi6_s5arT8xMupuNEnDM/ https://docs.google.com/document/d/1OjZoHNvn_vz6bhyww68B_KZB... linked from https://groups.google.com/a/chromium.org/g/blink-dev/c/POCUbyCqnrc/m/QcpmsLGwDQAJ https://groups.google.com/a/chromium.org/g/blink-dev/c/POCUb.... (This is just the first one I found, I don’t know if it’s well-written.)
- molodec 4y agoI am not a native English speaker. I could never understand the stress on active voice. "The vast majority of sentences in technical writing should be in active voice". https://developers.google.com/tech-writing/one/active-voice https://developers.google.com/tech-writing/one/active-voice This is stated as an axiom without any explanation.
- netr0ute 4y agoHere's why you should use the active voice: 1. It lets you know who/what is performing the action, instead of leaving it to the reader to figure it out. 2. It makes the writing less repetitive because each descriptive word becomes a verb, instead of "to be" being in every sentence.
- cudgy 4y agoPersonally I find active voice to be more repetitive as it tends toward a similar sentence structure of subject-verb and can also imply certainty in situations that are more nuanced. However, active voice and simple sentence structure should be used when possible to avoid redundant, flowery language.
- buzzy_hacker 4y agoActive voice is usually more clear, tight, and pleasant to read.
- karlmdavis 4y ago“We are raising your plan’s rates.” versus: “The plan’s rates have gone up.”
- kazinator 4y agoThe active voice removes the information about what agent is responsible for the action, which has the effect of removing clarity. The reader would like to understand cause-effect chains, whereas the passive sentences indicate that certain actions happen, as if spontaneously. Passive sentences are used in blame-deflecting language, such as statements that superficially look like apologies, but don't indicate who is at fault, and so do not indicate any acceptance of responsibility.
- photochemsyn 4y agoI wouldn't rely on Google to learn good practices for technical documentation (unless they want to release their complete internal technical documents on how their recommendation algorithms work, that is). Instead, check out a reliable open source project like SQLITE, they have great documentation: https://www.sqlite.org/arch.html https://www.sqlite.org/arch.html https://github.com/sqlite/sqlite https://github.com/sqlite/sqlite See previous discussion of sqlite structure here: https://news.ycombinator.com/item?id=32250426 https://news.ycombinator.com/item?id=32250426
- mikewarot 4y agoIn other courses, Google talks about recruiting from the graduate pool, perhaps they need some technical writers and this is a way for them to hire at lower cost?
- ruuda 4y agoThis course is great. I took it in person a few years ago, and I’ve since recommended it to quite a few people who got noticeably better at technical writing afterwards. There is not any great eye-opening insight in the course, it’s mostly good practices you already knew anyway, but it’s very useful to be reminded of them, and have them spelled out clearly in one place.