list-001 should GuidesAPI docsMarketing 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 docsMarketing 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 docsMarketing 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 docsMarketing 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 docsMarketing 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 (a complete sentence)
- ✓ “An
Orderresponse includes:” immediately before the list (a clause with enough context; see list-012) - ✓ “Configure the following settings. Each one takes effect after a restart.” before the list (a multi-sentence introduction, ending with a period)
- ✗ “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.
Clause introductions
Section titled “Clause introductions”list-012 should GuidesAPI docsMarketing A clause can introduce a list when a reader who is scanning the page can tell from the clause, and the heading above it, what the list contains, the way a heading tells a reader what its section contains. Give the clause a specific subject. When the clause can’t carry that context, introduce the list with a complete sentence.
Examples
- ✓ An
Orderresponse includes: - ✗ The response includes:
- ✓ The CLI supports the following commands:
- ✗ The CLI supports:
Rationale
A clause and its list work as one unit, so a reader who stops at the colon needs to know what is coming. A specific subject, or a heading that supplies one, tells them. A clause with a generic subject that ends on a bare verb makes the reader read the items to learn what they are, and a complete sentence would have told them first.
When content intervenes
Section titled “When content intervenes”list-006 should GuidesAPI docsMarketing 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 docsMarketing 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 docsMarketing 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 docsMarketing 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 docsMarketing 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.
Deprecated rules
Section titled “Deprecated rules”list-005(retired 2026-09-18): “Always precede a list with a colon, even when the introductory clause is a partial thought completed by the list items.” It restated list-004, which already accepts a partial clause with a colon. What a clause introduction needs is now list-012: enough context for a reader who is scanning.