Posted by James Scott, Technical writer
Technical writing is simple - you merely have to explain brutally complex technologies to relentlessly unforgiving audiences. It's unsurprising that so many engineers find writing documentation is the most painful part of their job. If you would like to teach your colleagues to become writers, the good news is Google's fun and interactive technical writing course materials are free and available for everyone to use! Alternatively, if you're a developer who would like to learn how to write more clearly, you can read through the course work for yourself or convince a colleague to teach the course at your organisation!
We researched documentation extensively, and it turns out that the best sentences in the world consist primarily of words. Our self-paced and facilitator-led courses will not only help software engineers choose the right words but also help to make the whole writing process a lot less scary. Perhaps software engineers won't become William Shakespeare or even William Shatner overnight, but hopefully they will gain the confidence to write something worth publishing. As working from home becomes more common, good documentation has never been more important in enabling software engineers to work independently.
Google introduced the technical writing courses, Technical Writing One and Technical Writing Two, in 2015. Since then, thousands of Google software engineers and product managers have taken and enjoyed the courses. In February 2020, we released the courses to the world.
The classes have the following structure:
Organizations can choose to host the live classes virtually or in-person.
The first course, Technical Writing One, covers the basics of technical writing. Students learn to start thinking about their audience before even putting pen to paper. For example, in one exercise, students are challenged to write instructions for putting toothpaste on a toothbrush. That might sound relatively simple, but here's the catch - your audience has never brushed their teeth before. That's not to say they have bad oral hygiene, but they don't even know what a toothbrush is. The exercise aims to get students to think about documenting a completely new technology.
Another important lesson that Technical Writing One teaches you is how to shorten the sentence
length in your documentation and how to edit unnecessarily long sentences. Hopefully once you
have taken the course, you might edit the preceding sentence down to something like the
following: Another important lesson that Technical
Writing One teaches you is to shorten
sentences length in your documentation and how to edit unnecessarily long
sentences.
The course also advocates using lists instead of walls of text, so here, in list form, are some other topics it covers:
Technical Writing Two builds on the techniques from the first course and is for those who already know verbs from adverbs. The course encourages students to express their creative side. For example, in one exercise, students find the best way to illustrate technical concepts. Spoiler alert: can you spot any issues with the following diagram?
Figure 1: Finding a website through DNS
Other intermediate techniques the course covers include:
Students take part in interactive exercises and peer review with a lab partner. Technical Writing Two also includes class discussions on documentation types and how to write the dreaded first draft.
If you would like to teach the courses at your own organization, see the facilitator guides. To review the pre-work and read through the training materials, see the course overviews.