Taras Bunyk

Revision checklist from Technical Writing One

Published: 2021-01-28T23:07:06.000Z

Google has nice course on technical writing. It's text itself is example on how to apply advice you will learn there. I finished first part twice, because first time I just did exercises and not made any notes. Before starting second part I noticed that I forgot almost everything, so I retook it with also taking some notes.

End of the course gives short summary, but here I'll give you mine checklist, which is a nice addition to revision checklist from Academic and Business Writing.

  • Define your audience. What they know, what they need to learn?
  • Define unfamiliar terms or link to their definition.
  • Use acronyms only if you define it first, it appears often in document and is significantly shorter than full text.
  • Make sure pronouns are unambiguous. Replace them (pronouns) with nouns when necessary.
  • Active voice is better then passive.
  • Avoid imprecise verbs - forms of "be", "occur", "happen". Remove "there is".
  • Remove unnecessary words. Reduce wordiness.
    • Is able to -> can
    • at this time -> now
  • Minimize adjectives and adverbs in educational texts.
  • Avoid idioms.
    • piece of cake -> easy
  • Write short sentences. Each sentence should focus on single idea.
  • Convert some long sentences to lists.
  • Use bulleted lists for unordered items and numbered for ordered. If meaning of list changes from reordering - it should be numbered.
  • Opening sentence of each paragraph should define what paragraph will be about.
  • Each paragraph should be about separate topic.
  • Each paragraph should answer 3 questions. (I am not very convinced about this).
    1. What you are telling your reader?
    2. Why it is important?
    3. How reader should use that knowledge? Or how should he know it is true?
  • Minimize use of parentheses. (They contain text that is not critical, so either text, or them could be removed.)
  • Turn on spellchecking. (My addition).

Vim users spellcheck like this:

:set spell spelllang=en_us

]s moves you to next misspelled word. [s - to previous. z= gives you a list of suggestions.