list-001 should GuidesAPI docs Use numbered lists for sequential or ordered content (steps, phases, priorities) and bulleted lists for non-sequential items.
Lists
Lists break dense information into scannable pieces, but only if the list type matches the content and the items are formatted consistently. These rules cover when to use numbered, bulleted, and description lists, and how to introduce and punctuate them. Step-by-step instructions have additional rules on the procedures page.
Numbered for sequence, bullets otherwise
Section titled “Numbered for sequence, bullets otherwise”Examples
- ✓ Numbered steps: 1. Install the CLI. 2. Authenticate. 3. Deploy your app.
- ✗ The same three sequential steps as a bulleted list
Rationale
Numbered lists imply order and bulleted lists do not, so the choice tells the reader whether sequence matters.
No single-item lists
Section titled “No single-item lists”list-007 should GuidesAPI docs Do not use a list to present only a single item.
Examples
- ✓ The upgrade requires a maintenance window.
- ✗ - The upgrade requires a maintenance window.
Rationale
A one-item list implies a set that is not there, so a sentence conveys it better.
Description lists for term pairs
Section titled “Description lists for term pairs”list-008 should GuidesAPI docs Use description lists (term + definition pairs) when presenting two or more terms that each require a definition or explanation.
Examples
- ✓ A description list pairing “Timeout” with “How long to wait for a response.” and “Retries” with “How many times to retry a failed request.”
- ✗ Timeout is how long to wait for a response, and retries is how many times to retry a failed request.
Rationale
Term-and-definition pairs read more clearly as a description list than as running text.
Colon after run-in terms
Section titled “Colon after run-in terms”list-009 should GuidesAPI docs In description lists with run-in headings, do not use a dash to separate the heading from its description; use a colon or period instead.
Examples
- ✓ Timeout: The maximum time to wait.
- ✗ Timeout — The maximum time to wait.
Rationale
A dash between a run-in term and its definition is easy to misread; a colon or period is clearer.
Introducing a list
Section titled “Introducing a list”list-004 should GuidesAPI docs If you introduce a list, table, or image with a description, end the sentence or clause with a colon if the sentence immediately precedes the content. Three patterns are acceptable: a partial clause ending with a colon, a complete sentence ending with a colon, or a multi-sentence introduction whose final sentence ends with a period.
Examples
- ✓ “The SDK supports the following platforms:” immediately before the list
- ✗ “The SDK supports the following platforms.” immediately before the list
Rationale
A colon signals the list that follows, and the accepted patterns cover the ways an introduction can lead in.
Colon after a partial introduction
Section titled “Colon after a partial introduction”list-005 should GuidesAPI docs Always precede a list with a colon, even when the introductory clause is a partial thought completed by the list items.
Examples
- ✓ “The response includes:” introducing the list
- ✗ “The response includes” before the list, with no colon
When content intervenes
Section titled “When content intervenes”list-006 should GuidesAPI docs Use a period (or other appropriate sentence-ending punctuation) after the introductory sentence when intervening material appears between the introduction and the list.
Examples
- ✓ “Configure the following settings. Changes take effect after a restart.” — a period, because a sentence intervenes before the list
- ✗ “Configure the following settings: Changes take effect after a restart.” — a colon followed by intervening material
Capitalize list items
Section titled “Capitalize list items”list-002 should GuidesAPI docs Start every list item with a capital letter, with narrow exceptions for lowercase product names or code literals that begin with a lowercase character.
Examples
- ✓ - Batch requests reduce overhead.
- ✗ - batch requests reduce overhead.
Rationale
A capital start keeps list items consistent with sentence conventions.
End punctuation by item type
Section titled “End punctuation by item type”list-003 should GuidesAPI docs End list items that are complete sentences with a period; omit end punctuation for items that are single words, lack a verb, are entirely in code font, or are entirely link text.
Examples
- ✓ - The API returns JSON by default.
- ✗ - The API returns JSON by default
- ✓ -
--verbose - ✗ -
--verbose.
Rationale
Ending full-sentence items with a period, and fragments without, keeps punctuation consistent and readable.
Consistent end punctuation
Section titled “Consistent end punctuation”list-011 should GuidesAPI docs If end punctuation would be inconsistent across items in a list, either rewrite for parallel construction or add end punctuation to every item.
Examples
- ✓ “Installs in seconds.”, “Runs on every platform.”, “Costs nothing for open source.” — every item punctuated
- ✗ “Installs in seconds.” followed by “Cross-platform” — end punctuation on some items only
Rationale
Mixed end punctuation across items looks careless, so make it uniform.
No etc. at the end
Section titled “No etc. at the end”list-010 should GuidesAPI docs Do not end an inline list with ‘etc.’ or ‘and so on’; instead, frame the introduction to make clear the list is not exhaustive.
Examples
- ✓ The CLI supports formats such as JSON and YAML.
- ✗ The CLI supports JSON, YAML, etc.
Rationale
A vague catch-all ending signals the list is incomplete without saying how; framing the introduction as non-exhaustive is clearer.