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.