111 lines
3.8 KiB
ReStructuredText
111 lines
3.8 KiB
ReStructuredText
.. _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. |