Blog - Page 2 of 257

Teaching the art of great documentation

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.

Courses overview

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:

Students complete self-study work before attending the live class. The self-study work is valuable on its own, even for students who will never attend the live class.
A facilitator guides students through a live class. The live class features practical exercises, class discussion, and extensive peer-to-peer feedback. Note that Google does not lead these live courses but provides extensive material to help facilitators prepare to lead them.

Organizations can choose to host the live classes virtually or in-person.

Technical Writing One

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:

Using active voice instead of passive voice.
Revising text into clear paragraphs.
Learning various self-editing techniques.

Technical Writing Two

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:

Organizing large doc sets.
Revising and reorganizing text.
Writing accurate descriptions.
Creating tutorials for beginners.

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.

Want to know more?

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.