We use two types of lists: numbered lists and bulleted lists. Use a numbered, or ordered, list when the order or priority of the items is important. Use a bulleted, or unordered, list when the order of the items is not important.
For both kinds of list, strive to keep all items in the list parallel. See Parallelism. Use a sentence style, making all the list items sentences.
Numbered (ordered) lists are most frequently used for procedures. Use numbered lists to show sequence for the items. Here are some guidelines for numbered lists:
- Make sure the list is sequential in nature and not simply a collection of items.
- Introduce a numbered list with a sentence setup text. End the setup fragment or sentence with a colon. Example: To configure the unit, do the following:
- Each item in the list should be parallel.
- Without exception, treat numbered list items as full sentences and end each list entry with a period, a colon, or a comma - when the entries are complete sentences or a mixture of fragments and sentences. In cases where the entries are short imperative sentences introducing commands or code, end them with colons.
- You may interrupt numbered lists with other paragraph styles, if the interruption is some explanatory text, commands, or code.
- Second-level steps are acceptable; avoid third-level steps.
- Avoid single-step procedures; the minimum number of steps in a procedure is two.
- Do not create numbered lists that emulate flowcharts. The reader should be able to execute the list of steps from first to last without branching or looping.
- Avoid over-using numbered lists, except in procedural documents such as tutorial and step-by-step guides.
- Use the # symbol for all list items. Use a three-space indentation for second-level items and for the explanatory text, commands, or code. Example:
Open the door.
Enter the room.
The room you enter may be dark. If it is not equipped with a motion sensor that triggers a light, you might want to turn on a light to avoid tripping over furniture.
Make a call.
- Pick up the receiver.
- Dial a number.
- Talk to the other party or leave a message.
- Hang up.
Turn off the light.
Leave the room.
Use bulleted, or unordered, lists to reduce wordiness and paragraph density, particularly when a sequence is not required. Here are some guidelines for bulleted lists:
- Introduce a bulleted list with a sentence. End the setup text with a colon. Example: To repair the unit, you will need the following:
- Each item in the list should complete the setup sentence staying parallel.
- Avoid interrupting bulleted lists with other paragraph styles.
- Second-level bullets are acceptable; avoid third-level bullets.
Use sentence style bullet lists.
Sentence style bullet lists are punctuated like sentences because all items in the list are sentences. End all bullets with a period or a colon if the bullet introduces a second level list. For example:
When setting the user code remember:
- make the user code easy to remember. Use a number that has a meaning for you
- change the code once a month
- do not disclose the user code to anyone else. This includes the security company
When setting the user code, it is important to remember a few things:
- Use a number that has a meaning for you.
- Change the code once a month.
- Do not disclose the user code to anyone else. This includes the security company.
Fragment style bullet lists and presentation style bullet lists are not acceptable for either in-code documentation or stand alone documentation. They can only be used for presentations.
Presentation style bullets have little or no punctuation. They are typically short phrases or even single words. They often start with a capital and end with no punctuation, unless they are full sentences. Use only for presentations.