Instructing the artwork of nice documentation


Posted by James Scott, Technical author

Technical writing is straightforward – you merely have to elucidate brutally advanced applied sciences to relentlessly unforgiving audiences. It is unsurprising that so many engineers discover writing documentation is essentially the most painful a part of their job. If you need to show your colleagues to turn out to be writers, the excellent news is Google’s enjoyable and interactive technical writing course supplies are free and obtainable for everybody to make use of! Alternatively, in the event you’re a developer who wish to learn to write extra clearly, you’ll be able to learn by way of the course work for your self or persuade a colleague to show the course at your organisation!

We researched documentation extensively, and it seems that the perfect sentences on the earth consist primarily of phrases. Our self-paced and facilitator-led programs is not going to solely assist software program engineers select the proper phrases but in addition assist to make the entire writing course of lots much less scary. Maybe software program engineers will not turn out to be William Shakespeare and even William Shatner in a single day, however hopefully they’ll achieve the arrogance to put in writing one thing price publishing. As working from residence turns into extra widespread, good documentation has by no means been extra vital in enabling software program engineers to work independently.

Programs overview

Google launched the technical writing programs, Technical Writing One and Technical Writing Two, in 2015. Since then, hundreds of Google software program engineers and product managers have taken and loved the programs. In February 2020, we launched the programs to the world.

The courses have the next construction:

College students full self-study work earlier than attending the reside class. The self-study work is efficacious by itself, even for college kids who won’t ever attend the reside class.

A facilitator guides college students by way of a reside class. The reside class options sensible workouts, class dialogue, and in depth peer-to-peer suggestions. Be aware that Google doesn’t lead these reside programs however offers in depth materials to assist facilitators put together to steer them.

Organizations can select to host the reside courses nearly or in-person.

Technical Writing One

The primary course, Technical Writing One, covers the fundamentals of technical writing. College students study to begin desirous about their viewers earlier than even placing pen to paper. For instance, in a single train, college students are challenged to put in writing directions for placing toothpaste on a toothbrush. Which may sound comparatively easy, however this is the catch – your viewers has by no means brushed their enamel earlier than. That is to not say they’ve unhealthy oral hygiene, however they do not even know what a toothbrush is. The train goals to get college students to consider documenting a very new know-how.

One other vital lesson that Technical Writing One teaches you is easy methods to shorten the sentence size in your documentation and easy methods to edit unnecessarily lengthy sentences. Hopefully after getting taken the course, you may edit the previous sentence all the way down to one thing like the next: One other vital lesson that Technical Writing One teaches you is to shorten sentences size in your documentation and easy methods to edit unnecessarily lengthy sentences.

The course additionally advocates utilizing lists as an alternative of partitions of textual content, so right here, in listing kind, are another matters it covers:

Utilizing lively voice as an alternative of passive voice.

Revising textual content into clear paragraphs.

Studying varied self-editing methods.

Technical Writing Two

Technical Writing Two builds on the methods from the primary course and is for individuals who already know verbs from adverbs. The course encourages college students to precise their inventive aspect. For instance, in a single train, college students discover the easiest way for example technical ideas. Spoiler alert: can you notice any points with the next diagram?

A diagram titled Finding a website through DNS, with seven boxes of varying colour, size, and shape connected by lines in various directions.

Determine 1: Discovering an internet site by way of DNS

Different intermediate methods the course covers embrace:

Organizing giant doc units.

Revising and reorganizing textual content.

Writing correct descriptions.

Creating tutorials for rookies.

College students participate in interactive workouts and peer overview with a lab companion. Technical Writing Two additionally contains class discussions on documentation sorts and easy methods to write the dreaded first draft.

Wish to know extra?

If you need to show the programs at your individual group, see the facilitator guides. To overview the pre-work and browse by way of the coaching supplies, see the course overviews.