Technical Writing Courses from Google | Hacker News Reader

Technical Writing Courses from Google

developers.google.com

165 pointssebnun36 comments

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.

Far as their public stuff goes, I'd tend to agree with you. If the OpenBSD folks published a course like this, though...

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.

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.

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.

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?

Angular docs are pretty good. Also didn't have trouble with GCP docs.

Dart's documentation is comprehensive, well-written, and provides tons of meaningful examples.[0].

[0]: https://dart.dev/guides

I've found the GCP documents well-written and nicely structured, at least around cloud storage and pubsub.

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.

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.

Flutter's documentation is fantastic. A lot of effort went into it, and it shows.

The Go documentation is high quality.

A 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/ - 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.

I 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 This is stated as an axiom without any explanation.

Here'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.

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

Active voice is usually more clear, tight, and pleasant to read.

“We are raising your plan’s rates.”

versus:

“The plan’s rates have gone up.”

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

In technical writing, which is often trying to be as concise as possible, active voice usually allows the shortest sentences, which, as a practice, tend to be more clear.

However, there are instances when the passive voice is important and should be used. For instance, if you are trying to put an emphasis on the fact that a subject receives an action. This can often be done in a passively voiced sentence where you clarify a certain relationship. In other words, passive voice can be an important part of adding context.

The idea that you should never use passive is largely just people hearing a rule and thinking it is the end all be all. In reality, you're better off learning what both types of structure do, and then choosing one or the other with a specific goal in mind.

As a native English speaker, I first learned of "active voice" and "passive voice" when I started using tools to check (and correct) my writing.

In terms of sentence structure, "active voice" means the subject of the sentence performs an action; "passive voice," therefore, is somewhat the contrary: the verb acts upon the subject.

See https://www.grammarly.com/blog/active-vs-passive-voice/ for more.

(p.s. I do not work for grammarly and I am not promoting the app)

The is my favorite example of active vs passive:

First active

> I went to the woods because I wished to live deliberately, to front only the essential facts of nature, and see if I could not learn what it had to teach, and not, when I came to die, discover that I had not lived.

Now passive:

> A decision was made to go to the woods because of a desire for a deliberate existence and for exposure to only the essential facts of life, and for possible instruction in its educational elements, and because of a concern that at the time of my death the absence of a meaningful prior experience would be apprehended.

https://theamericanscholar.org/writing-english-as-a-second-l...

I 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://github.com/sqlite/sqlite

See previous discussion of sqlite structure here:

https://news.ycombinator.com/item?id=32250426

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

I've heard Google uses design docs pretty extensively for internal projects. Does anyone have a publicly shared example?

There are many public ones on chromium-dev and blink-dev, e.g. https://docs.google.com/document/d/1OjZoHNvn_vz6bhyww68B_KZB... linked from 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.)

I 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/

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

Did you take the course? I saw on an HN thread mixed reviews.

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

Ha! 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.

Or you could just take a look at the linked course and learn something. It's pretty good and worth working through.

I find cloud documentation to be pretty clear most of the time

Reply on news.ycombinator.com