Lists and tables

Lists and tables are among the most powerful formatting tools in documentation — and among the most misused. Used correctly, they make complex information scannable and easy to act on. Used incorrectly, they fragment information that flows more naturally as prose and make documentation feel choppy and disorganized.

When to Use a List

Use a list when:

• You have three or more items that would be unwieldy in a sentence.
• The items are discrete and parallel in nature.
• The reader needs to be able to scan the items individually.
• Order matters and you want to make that explicit (ordered list) or order does not matter and you want equal visual weight (unordered list).

Do not use a list when:

• You have only two items — these almost always read better in a sentence with "and" or "or."
• The items are part of a continuous explanation or argument that would lose meaning if disconnected.
• The items are so short they look odd as list items ("Yes," "No," "Maybe").
• You are breaking up a paragraph just to add visual variety.

Ordered Versus Unordered Lists

Use an ordered list (numbered) when:

• The sequence of items matters — steps in a procedure must be done in order.
• You will refer back to items by number ("return to step 3 if...").

Use an unordered list (bulleted) when:

• The items can be acted on or considered in any order.
• You are listing options, features, requirements, or examples.

Definition Lists

Use a definition list (term paired with its explanation) when you're presenting a set of terms and their meanings — a glossary, a set of parameter names with descriptions, or any term-explanation pairing where the term itself functions as a label rather than a list item in the usual sense.

• Prefer a definition list over an ordered or unordered list when each item has exactly one clear "label" and one "explanation," and the label is what the reader will scan for.
• Prefer a two-column table instead when there are three or more properties to show per term (for example, a parameter's name, type, and description together) — at that point you're showing structured, multi-column data, which is what tables are for.

Writing Consistent List Items

All items in a list must be grammatically parallel. Choose a structure and apply it to every item in the list.

Punctuation in list items

See the List Parallelism section of the Punctuation guide for the full rule on periods and fragments in list items. In short: if every item is a complete sentence, end each with a period; if every item is a fragment, use no ending punctuation; never mix the two within the same list.

If list items contain internal punctuation (commas, semicolons), consider using a table instead.

Links within list items

A list item may itself be a link, or may contain one — but be consistent within a single list. If some items in a list link out to further reading and others don't, either add a matching link to every item or move the linked items into their own separate list, so a reader isn't left guessing why some items behave differently than others.

Nested Lists

Limit nesting to one level deep. A list within a list within a list is almost always a sign that the information should be restructured — perhaps as a heading hierarchy or a table.

A second level of nesting is acceptable when a list item genuinely has sub-items that belong under it. More than two levels creates a structure that is visually complex and harder to navigate than the alternatives.

When to Use a Table

Use a table when you have information with a consistent structure that benefits from column alignment — where comparing values across rows is useful, or where multiple properties of multiple things need to be shown together.

Good candidates for tables:

• Feature comparisons across plans or tiers
• Parameter references with names, types, and descriptions
• Keyboard shortcuts with keys and actions
• "Before and after" or "do/don't" comparisons
• Error codes with descriptions and resolutions

Do not use a table when a list would suffice. A single-column table is almost always better as a list.

Writing Effective Tables

Column headers

Every table needs column headers. Headers should be short, descriptive, and sentence case. They tell the reader what type of information each column contains.

Cell content

Keep cell content as concise as possible. A table cell that contains three paragraphs of prose is not a table — it is a document inside a table. If cells need extensive explanation, link to dedicated articles instead.

Use consistent formatting within each column. If one cell in a column is a complete sentence, all cells in that column should be complete sentences.

Table accessibility

For the full accessibility requirements around header markup and avoiding tables for layout purposes, see the Tables section of the Formatting Standards guide. As a summary: mark header rows as headers (not just bold text) so screen readers announce them correctly, and never use a table purely for visual layout.

Wide and long tables

A table with many columns may not render well on a narrow screen or in a PDF export. If a table has more columns than can reasonably fit, consider whether some columns could be split into a separate, related table, or whether the least essential columns could be dropped in favor of a link to a fuller reference.

A table with a very large number of rows (a long error-code reference, for example) is still appropriate as a table — length alone isn't a reason to switch formats — but consider adding a short introductory note on how to search or scan it if your platform doesn't support in-page filtering, so the reader isn't left scrolling through hundreds of rows with no way to narrow them down.

Avoiding List Overuse

A common and damaging pattern in documentation is converting all prose into lists. An article that is entirely bullet points with no connecting prose feels fragmented and is harder to read than an article that uses prose for explanation and lists where lists genuinely help.

The test: read your list aloud as a sentence or a short paragraph. If it sounds natural, write it as prose. If converting it to prose makes it unwieldy, keep the list.

Self-Audit Checklist

Before publishing, check lists and tables against these questions:

• Does every list have three or more items, rather than two items that would read better as a sentence?
• Is an ordered list used only when sequence genuinely matters?
• Are all list items grammatically parallel with each other?
• Is punctuation consistent across all items — either all sentences with periods, or all fragments with none?
• Is a definition list or table used instead of a plain list wherever items pair a term with an explanation or multiple properties?
• If any list items are links, are all items in that list links, or are linked items separated into their own list?
• Is nesting limited to one level, with two only when genuinely necessary?
• Does every table have a marked header row, and is it used only for genuinely tabular data?
• Is every table cell concise, with longer explanations linked out rather than crammed into a cell?
• Have wide tables been checked for how they render on narrow screens or in exports?
• Would reading any list aloud as prose sound natural — and if so, has it been converted to prose instead?