openstack-manuals/doc/contributor-guide/source/writing-style/lists.rst

Lists

When reading a document for the first time, users scan through pages stopping only on the content that stands out, such as titles, lists, links, diagrams, and so on. Lists help to organize options, as well as help readers to find information easily.

When listing items, follow these guidelines:

• Use a bulleted list for options. Create a bulleted list when you need to describe more than three options.
• Use a numbered list for steps.
• Use a definition list to explain terms or describe command-line parameters, options, or arguments.
• Use a colon at the end of the sentence that introduces a list.
• Use the same grammatical structure (aka parallel structure) for all items in a list.
• Start each option with a capital letter.

When listing options in a paragraph, add and or or before the last item in a list. Use a serial (Oxford) comma before these conjunctions if they connect three or more items.

Punctuation in lists

In bulleted lists:

• If you list individual words or phrases, do not add a period at the end of each list item.
• If you use full sentences, add a period at the end of each sentence.
• If your list includes both individual words or phrases and full sentences, be consistent and either add or do not add periods to all items.

In numbered lists:

• Add periods at the end of steps.
• If an item of a numbered list is followed by a code block that illustrates how to perform the step, use a colon at the end.