Lists

A list is for things the reader compares or works through in turn. Prose that has been chopped into fragments is not a list; it is prose with the connective tissue removed, and the reader has to put it back.

Three items make a comfortable list. Two are usually a sentence with an and in it.

Intros

Introduce a list with a complete sentence, then a colon.

Recommended: A landed commit carries three trailers:

Not recommended: A landed commit carries:

The second reads as a sentence the list has to finish, which means the reader cannot take any item on its own. It also breaks the moment an item is reordered or removed.

Keep the introduction and the list in agreement about what the items are. If the sentence says three trailers, three trailers follow — not two trailers and a note about a third.

Never introduce a list with a fragment ending in a dash, and never with no mark at all.

Punctuation

Punctuate by what the items are, and punctuate every item in a list the same way.

Items that are complete sentences take a capital and a full stop:

Recommended: The subject is at most 50 characters.

Items that are not — a name, a phrase, a value — take neither:

Recommended: the commit subject

Do not end items with semicolons, and do not put a conjunction before the last one. Both are attempts to make a list read as a sentence, and a list that wanted to be a sentence should have stayed one.

Ordered or unordered

Number a list when the order is part of the meaning: steps to follow, a sequence, a ranking. Numbering an unordered list tells the reader that item 1 comes before item 2 in some way, and they will look for the way.

Leave a list unnumbered when the items are alternatives or members of a set, even a set with a natural order to it.

Nesting

One level of nesting is usually one too many already. If a list needs a second, the items have become sections and want headings instead — see Capitalization for how to set those.