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).
- What you are telling your reader?
- Why it is important?
- 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.