Best practices for writing with lists

Lists organize important information so that readers can scan content faster. Use a list to organize multiple steps or items. Avoid writing tasks in paragraph form, unless the task contains only 1 step.

When you include lists in your content, consider these best practices:

• Introduce lists with a complete lead-in sentence that describes the purpose or the content of the list.
• Include more than 1 item in a list.
• Introduce only 1 idea, item, or action in each list item.
• Use no more than 2 levels in a list: a primary list and a sublist.
  • Use sublists sparingly to avoid overcomplicating information.
  • Ensure sublists have more than 1 item.
• Capitalize the first letter of every list item.
• In general, follow these punctuation guidelines for the items in a list:
  • If the list items are complete sentences, include end punctuation.
  • If the list items are characters, words, or phrases, don't include end punctuation.
• Use parallel sentence construction in list items. For example, start all list items with verbs, or end all list items with punctuation.
• In task steps, avoid linking to other topics within the task.
• Use lists in tables sparingly.

Use these best practices to make docs accessible for all audiences. For more guidance on making docs more accessible using lists, see Write accessible documentation.

Choose the best list

Choose from the following lists based on your content:

Type of list	When to use	More information
Bulleted list	When the list item order isn't important, such as a list of options.	See Bulleted lists.
Numbered list	When the order of the list items is important or the user is following sequential steps, such as a task.	See Numbered lists.
Definition list	For a list of descriptions, definitions, associations, or explanations, such as a glossary or a set of terms.	See Definition lists.