| .. _lists: |
| |
| Lists |
| ##### |
| 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 :ref:`parallelism`. Use a sentence style, making all the list items |
| sentences. |
| |
| 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. |
| |
| a. Pick up the receiver. |
| |
| b. Dial a number. |
| |
| c. Talk to the other party or leave a message. |
| |
| d. 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. |