Documentation

How to improve a list

Lists are common in technical writing. One of my duties is to instruct readers on what to do, step-by-step. Writing lists may seem easy, but I’ve seen a lot of manuals that ignore parallel sentences, emphasize words randomly, and forget punctuation.

Bad example of a list

These milk frother instructions came from a Nespresso Aeroccino manual.

CLEANING AFTER EVERY USE

  1. Remove from base and dismantle whisk (no tools needed). Note: when you have finished using the Aeroccino 3, switch OFF at the base with the main switch.
  2. Remove the seal from the lid to clean both parts. Rinse and clean with a damp cloth.
  3. Jug is waterproof but NOT dishwasher safe.
  4. Clip one of the whisks on to the inner base of the jug and to avoid loss, clip the other on to the lid (or in whisk storage when using the Aeroccino 3).

How to improve the list

The list is easy to understand, but the information could be presented in a clearer and more concise way. Here are my suggestions:

Edited list

CLEANING AFTER EVERY USE

Caution: Aeroccino 3 is waterproof but not dishwasher safe. Wash by hand.

Note: After using Aeroccino 3, switch it off at the base.

  1. Remove jug from base and dismantle whisk (no tools needed).
  2. Remove seal from lid.
  3. Rinse and clean seal, lid, and jug.
  4. Clip one whisk on to inner base of jug.
  5. Clip other whisk on to lid or in whisk storage.

Remember, your list must convey information clearly. Write instructions with parallel sentences, remove random emphasis on words, place important notes before the list, and break down long-winded steps.