How (and why) Google teaches technical writing to engineers

Back in 2015, Google’s technical writers stepped up to teach their engineering colleagues the essential skills of the tech comm trade. Today, their courses reach beyond Google’s own networks – here is how you can get involved.

Text by Dirk Göhmann

Inhaltsübersicht

Image: © alvarez/istockphoto.com

Before we take a closer look at how Google teaches technical writing to engineers, let’s take a moment to understand why Google does this in the first place. After all, isn't technical writing best left to professional technical writers, whereas engineers are expected to write code and develop new software solutions?

This is not the way we look at it here at Google. Instead, the guiding principle we adhere to is:

Every engineer is also a writer.

Why has Google adopted this principle? The reality, not only at Google, is that the need for documentation far exceeds the capacity of available technical writers. For this reason, it is vital that engineers can contribute to documentation needs and feel confident in doing so. After all, clear documentation drives productivity, whereas vague documentation generates frustration. So, helping engineers write clearer documentation is a powerful lever to ensure user satisfaction by empowering users to reach their goals in a fast and efficient manner.

As an added bonus, improving engineers' writing skills can also alleviate some of the strain on technical writers, who frequently work with content provided to them by engineers when putting together new sets of documentation.

“Documentation” is not limited to public product documentation. It also applies to a myriad of other technical content, usually internal to Google, such as:

  • Documentation of internal systems
  • Design documents
  • Code comments
  • Test plans
  • Presentations

With such varied needs for written communication, you'd think that communication courses would occupy a substantial part of the curriculum at engineering schools. However, many engineers never take a single technical writing course during their time at university. And this despite the fact that being able to convey thoughts and share knowledge with others is a crucial skill engineers need to master to move their careers forward. When engineers become better writers, it is not only your users that benefit but your whole organization. After all, better writing skills translate into improved communication, design, and collaboration skills.

To address this situation, in 2015, a group of engaged technical writers at Google created the first course designed to teach engineers some of the tricks of the (technical writing) trade, Technical Writing One. This course proved to be immensely popular within Google, with over half of all Google engineers completing at least part of the self-study portion of the course. The strong interest in technical writing skills shown by engineers led to the creation of Technical Writing Two in 2017.

 

Technical writing courses at Google

Now that we’ve clarified the why, let’s move on to the how.

Google offers two technical writing courses: the introductory Technical Writing One, and the intermediate Technical Writing Two. Both courses are designed as in-class (or virtual) sessions led by an instructor. Each of the courses lasts 2.5 hours and includes self-paced online pre-class material, which we recommend reviewing prior to attending a live session (working through these materials requires an additional hour or two).

Both courses draw heavily on integrated exercises, meaning participants won’t be listening to a lecture on the principles of technical writing but will be getting their hands dirty from the onset – workshop style. We place a strong emphasis on discussions, both in small breakout groups of two and with the full group of course participants. Experience shows that the best sessions are the ones where the participants are strongly engaged and share their thoughts and experiences – there’s always something we can learn from each other.

 

Technical Writing One

Technical Writing One teaches engineers the critical basics of technical writing, covering themes such as:

  • Audience – Knowing your audience is critical to ensuring your documentation is accessible to readers and picks them up at the right point. Beware of the curse of knowledge, which can lead documentation to become inaccessible to less experienced readers because it assumes too much pre-existing knowledge.
  • Active voice – As a rule of thumb, using the active voice is preferable to writing in the passive voice.
  • Lists – Harness the power of lists (bulleted and ordered) to make your content easier to parse for readers.
  • Editing and clarifying – Review your own (or other people’s) content! No one, not even an experienced technical writer, can pop out a perfect text in one go. A second glance at your writing helps avoid problematic patterns such as overly long sentences or the overuse of the passive voice. The final result is more readable and usable content.

 

Technical Writing Two

Technical Writing Two focuses on intermediate tasks in technical writing such as:

  • Writing is rewriting – Wait, wasn’t editing already addressed in Technical Writing One? Yes, it was, but we think editing is so important that it is worth returning to this topic and introducing advanced strategies for improving content through an iterative process. This includes topics such as organizing the structure of your document and using headings.
  • Illustrations – As the old saying goes: “A picture is worth a thousand words”. We discuss strategies that can help you create diagrams that make it easy for readers to relate to complex issues.
  • Descriptions – Especially when explaining concepts, being able to describe systems and technologies is a crucial skill. This exercise introduces some approaches that will help you write better and clearer descriptions.
  • Tutorials – A frequent motivation for producing written content is to empower users to achieve a specific, non-trivial goal, or to teach a new technology. Tutorials are a hands-on way to convey knowledge of this type. They can explain prerequisites and concepts, as well as provide step-by-step instructions that are easy to follow and lead users to successfully complete a task.

 

Can I take or teach the course?

Yes, you can! After all, it wouldn’t be fair to tell you all about these courses if they were accessible only to Google employees. While these courses were developed for internal use, in 2020, Google decided to make them available externally – for students as well as for facilitators who would like to teach the courses publicly, or hold dedicated sessions for engineers within their own organization, university students, etc.

 

For students

Check the schedule on the Announcements page [2] to see when the next public sessions will take place, and get started by reviewing the self-paced pre-class work available at

https://developers.google.com/tech-writing/overview.

 

For facilitators

Want to teach this course? You can find everything you need to know on the Overview page for facilitators [3]:

  • Links to the dedicated Facilitator’s Guides for Technical Writing One and Technical Writing Two.
  • The slide decks for both courses (we have versions for in-class and virtual sessions), which include detailed speaker notes. Note that you’ll need to join the technical-writing-instructors(at)googlegroups.com group to gain access to the slide decks, as described on the Overview page.
  • Video guides for each of the exercises contained in Technical Writing One and Technical Writing Two. These short videos go beyond the speaker notes you’ll find in the slides and are a great learning resource for aspiring facilitators who are preparing to teach their own classes.
  • A short video explaining the basic technical requirements for running virtual training.

From time to time, we also hold dedicated Train the Trainersessions; upcoming sessions are announced in the schedule available on the Announcements page.

 

Some final words for future facilitators

I’d like to end with some tips and notes for aspiring facilitators:

  • Scared you don’t have the skills it takes to teach this course? In reality, any good facilitator can lead this course; you don't need to be an expert in technical writing. Having some experience can come in handy, as it allows you to share some personal anecdotes. But a background in technical writing is definitely not a prerequisite to becoming a facilitator, and many non-technical writers have successfully taught the course.
  • If you want to gain hands-on experience before facilitating a technical writing course on your own, take the course as a student. This is the most straightforward way to familiarize yourself with course content and understand how the different topics are taught (taking notes never hurts!). Another great way to get into things is to co-teach with a second, more experienced facilitator. This means less content to cover, and you’ll have someone around who can support you if needed.
  • During the course, continuously encourage participants to speak up and share their opinions and views. People can be shy, especially in virtual settings, and some extra encouragement often helps break the ice. Training sessions always profit from the diverse perspectives that the participants can contribute. And for you as the facilitator, it’s much more fun to have a dialogue with participants than holding an endless monologue.
  • Never forget: Even as a facilitator, you can learn a lot! Not only will you be honing your presentation skills, but you’ll learn more about how others think about different problems and challenges associated with technical writing.

And last but not least: Happy teaching!