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