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 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
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.
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
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.
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
- define your audience
- determine what your audience needs to learn
- fit documentation to your audience
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
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.