Skip to content

Instantly share code, notes, and snippets.

@thyrlian
Last active September 26, 2020 21:21
Show Gist options
  • Save thyrlian/5e2a761d15ba30edce72af295b36f4a4 to your computer and use it in GitHub Desktop.
Save thyrlian/5e2a761d15ba30edce72af295b36f4a4 to your computer and use it in GitHub Desktop.
Notes taken from Technical Writing Courses by Google Developers (https://developers.google.com/tech-writing)
  • 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) ...
  • 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.

  • 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.

Recap

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment