zephyr/doc/documentation/detailed_lists.rst

.. _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.