Lists

Numbered Lists

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 or a colon - whether 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 should be 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. First-level items should use Arabic numerals; second-level items should use lowercase letters. Example:

1. Open the door.
2. 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.

3. Make a call.
   1. Pick up the receiver.
   2. Dial a number.
   3. Talk to the other party or leave a message.
   4. Hang up.
4. Turn off the light.
5. Leave the room.

Bulleted Lists

Use bulleted, unordered, lists to reduce wordiness and paragraph density, particularly when sequence is not a requirement. 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:

Incorrect

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

Correct

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.