List etiquette

All items in a list must either end in punctuation, or not. Do not mix in the same list.

Avoid nesting lists more than three levels. Consider break the list into sections when nesting is too deep.

When the content presented in each bullet point is lengthy, it can still result in an undesirable wall of text.

When the list items start with a term, separate the term from the rest of the item with an em-dash.

• Em-dash — Something to include in lists as a separator. Put spaces on either end of the dash.
• Colon: Do not use colons. (But if you are going to use colons, use them consistently in you doc set.)

A list item may begin with lead-in bold text to indicate the this the list item is about. If you use it, do it for all items in the list

• North is a cardinal direction
• East is where the sun rises
• South is at the bottom of maps focusing on the Northern Hemisphere
• West has dragons

Compact vs open lists

Use compact lists when the items are short — a small sentence or less.

A compact list has no whitespace between the list items:

• Thing one
• Thing two
• Thing three

An open list (the default in Heretto) has whitespace between the items.

• Thing one

• Thing two

• Thing three

<ul>
    <li>
        <p>Thing one</p>
    </li>
    <li>
        <p>Thing two</p>
    </li>
    <li>
        <p>Thing three</p>
    </li>
 </ul>

Unordered lists

When the list order is not important, use an unordered list (<ul>).

• Unordered list item.
• Unordered list item.
  • Sublist
  • And another
• Another list item.

  A paragraph in the list. How does it wrap? Lets enter a lot of text so we can test the result of wrapped text on the published page. Hopefully this is enough.

• Last list item.

Ordered list

Ordered lists (<ol>) are for enumerated steps, or for illustration/image call-outs.

Simple lists

Short, phrase-like content, such as in documenting the materials in a kit or package. In output, the list has no bullets, on the assumption that each item is short enough to fit on one line, and needs no additional differentiation from its neighbors.

A simplelist (sl):

This is an option instead of using a Compact unordered list.

Definition lists

Use definition lists (<dl>) them for Screen/Page Options/Properties in Express Setup.

Parameter lists

Parameter lists contain a list of terms and definitions that describes the parameters in an application programming interface. This is a special kind of definition list that is designed for documenting programming parameters.