85107272be
Based off conversation at the PTG, we agreed it would be beneficial to ensure the contrib-guide is clearly marked as the doc contrib guide outside of the title. This change includes a redirect. Change-Id: I5abf915f0b94a482afa961e6b86364c26aae5d79
45 lines
1.5 KiB
ReStructuredText
45 lines
1.5 KiB
ReStructuredText
=====
|
|
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.
|