Notes taken from Technical Writing Courses by Google Developers (https://developers.google.com/tech-writing)

TechnicalWriting.md

Technical Writing Courses

Technical Writing One

Just enough grammar

Words

• Use terms consistently: if you rename a term in the middle of a document, your ideas won’t compile (in your users’ heads).

• You may specify a shortened version of a long-winded concept name, for instance:

  • Protocol Buffers (or protobufs for short) ...

Active voice

• The vast majority of sentences in technical writing should be in active voice, because active voice is usually clearer.

• Distinguish active voice from passive voice:

  • Active Voice Sentence = actor + verb + target

  • Passive Voice Sentence = target + verb + actor

• Active voice provides the following advantages:

  • Most readers mentally convert passive voice to active voice.

  • Passive voice obfuscates your ideas, turning sentences on their head. Passive voice reports action indirectly.

  • Some passive voice sentences omit an actor, which forces the reader to guess the actor's identity. Good sentences in technical documentation identify who is doing what to whom.

  • Active voice is generally shorter than passive voice.

Clear sentences

• Choose strong verbs

  • To engage and educate readers, choose precise, strong, specific verbs.

  • Reduce imprecise, weak, or generic verbs, such as the following:

    • forms of be: is, are, am, was, were, etc.

    • occur

    • happen

• Reduce there is/there are

  • Sentences that start with There is or There are marry a generic noun to a generic verb. Providing a real subject and a real verb makes the sentences clearer.

  • You can sometimes repair a there be sentence by moving the true subject and true verb from the end of the sentence to the beginning.

  • For sentences start with there be without identifying the receiving entity, to fix it, you can create a subject.

• Minimize certain adjectives and adverbs

  • Adjectives and adverbs can make technical documentation sound dangerously like marketing material.

  • Feed your technical readers factual data instead of marketing speak.

  • Refactor amorphous adverbs and adjectives into objective numerical information, to gain accuracy and believability.

Short sentences

Lists and tables

Paragraphs

Audience

Documents

Punctuation

Markdown

Technical Writing Two

Self-editing

Organizing large docs

Illustrating

Creating sample code

Recap

It's all about eliminating ambiguity, making the technical documentation clear and engaging.