Technical Writing One: Notes

gmarik 4 min

Do you want to improve your technical writing? Google Developers were kind enough to publish Technical Writing One so there are no excuses to not get better at it.

It takes ~2 hours to finish it’ll immediately improve your writing.

The course is so polished that the table of contents serves as “fast and hard rules” index which I decided to turn into a blog post of my own, for a quick reference.

Just enough grammar

TLDR: know your tools.

Part Of SpeechDefinitionExample
Nounsa person, place, concept, or thingApple is a company.
Pronounsa noun that substitutes for another nounApple is a company. They invented iPhone.
Verban action word or a phraseApple designs iPads as well.
Adverba word or phrase that modifies a verb, an adjective, or another adverbApple is slowly taking over the world.
Adjectivesa word or phrase that modifies a nounApple’s products are well designed.
Prepositiona word or phrase specifying the positional relationship of two nounsApple’s products are the best in the world.
Conjunctiona word that connects two nouns or phrasesApple’s iPhones and iPads are the fastest computers.
Transitiona word or phrase that connects two sentencesApple’s is great. However, their products are quite expensive.

Active Voice vs Passive Voice

TLDR: The vast majority of sentences in technical writing should be in active voice

Active Voice Sentence = actor + verb + target

Passive Voice Sentence = target + verb + actor

Clear Sentences

TLDR: Remove indirection and stick with active voice.

Verb is the most important part of a sentence. Pick the right verb and the rest of the sentence will take care of itself.

Reduce imprecise, weak, or generic verbs, such as the following: - forms of be: is, are, am, was, were, etc. - occur - happen

Weak VerbStrong Verb
The error occurs when clicking the Submit button.Clicking the Submit button triggers the error.
This error message happens when…The system generates this error message when…
We are very careful to ensure…We carefully ensure

Short Sentences

TLDR: focus on a single idea.

Lists and Tables

TLDR: reduce cognitive reading load with lists and tables.

Paragraphs

TLDR: Like sentences, focus paragraphs on single a idea/topic.

Writing is untangling the dependencies among the parts of a topic, and presenting those parts in a logical stream that enables the reader to understand you.

Audience

TLDR: cater to your audience, assume nothing.

good documentation = knowledge and skills your audience needs to do a task − your audience’s current knowledge and skills

Documents

TLDR: establish scope, goals, and audience. Divide and conquer.

Punctuation

TLDR: disambiguate.

Summary

My personal additions would be consistency. Having different styles/approaches in the same document is confusing at least and discrediting at most.

I’ve noticed that often times my writing is not consistent enough:

Although, I’d like to also point out, that consistency is an optimization and should be applied once the foundation of a document is laid out.

Elsewhere

Read More
SRE Course: part 01: abstract
Comments
read or add one↓