Do you want to improve your technical writing? Google Developers were kind enough to publish Technical Writing One so there are no more excuses to not get better at it.
The course takes ~2 hours to finish and 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 Speech | Definition | Example |
|---|---|---|
| Nouns | a person, place, concept, or thing | Apple is a company. |
| Pronouns | a noun that substitutes for another noun | Apple is a company. They invented iPhone. |
| Verb | an action word or a phrase | Apple designs iPads as well. |
| Adverb | a word or phrase that modifies a verb, an adjective, or another adverb | Apple is slowly taking over the world. |
| Adjectives | a word or phrase that modifies a noun | Apple’s products are well designed. |
| Preposition | a word or phrase specifying the positional relationship of two nouns | Apple’s products are the best in the world. |
| Conjunction | a word that connects two nouns or phrases | Apple’s iPhones and iPads are the fastest computers. |
| Transition | a word or phrase that connects two sentences | Apple’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
- distinguish passive vs active voice
- recognize passive verbs
- imperative verbs are typically active
- active vs passive voice in complex sentences
- prefer active voice to passive voice
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 Verb | Strong 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… |
- reduce there is/there are
- minimize certain adjectives and adverbs Let the reader make their own conclusion: provide facts and data instead of qualifications.
Short Sentences
TLDR: focus on a single idea.
- focus each sentence on a single idea
- convert some long sentences to lists
- eliminate or reduce extraneous words
- reduce subordinate clauses
- distinguish that from which
Lists and Tables
TLDR: reduce cognitive reading load with lists and tables.
- choose the correct type of list
- keep list items parallel
- start numbered list items with imperative verbs
- punctuate items appropriately
- create useful tables
- introduce each list and table
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.
- state your document’s scope
- state your audience
- establish your key points up front
- write for your audience
- break your document into sections
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:
- missing dots
- mix of capitalized/non-capitalized words in a sentence
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.