Skip to main content

Lists (Ordered and Unordered)

Last updated on
Open a doc issue   |   Edit this page

Lists play a crucial role in enhancing the readability and organization of information.

They help in breaking down complex instructions, features, or concepts into manageable, easy-to-digest pieces. Incorporating ordered and unordered lists effectively can significantly improve the quality and effectiveness of the documentation.

Basic guidelines

  • Use parallel writing structures for similar things.
  • Use lists to present complex text in a way that's easy to scan.
  • A list should have at least two items but no more than seven items

Correct

Lists are greate for:

  • Easy navigation.
  • Quick scanning.
  • Efficient comprehension.

Incorrect

Lists are great because they help uses with navigation, make it easy for scanning the document quickly, and they're also good for understanding complex information efficiently.

Unordered lists (bullets)

Use bulleted lists for things that have something in common but don't need to appear in a particular order.

Correct

The benefits of DevOps are:

  • Faster deployment
  • Improved collaboration
  • Higher quality software

Incorrect

How to merge a pull request:

  • Review the code changes.
  • Run automated tests.
  • Merge the pull request.

Why this is incorrect: Using a bulleted list for the process that should be sequential.

Ordered lists (numbered)

Correct

  1. Tun on the computer.
  2. Log into your computer.
  3. Open the browser.

Incorrect

  1. Importance of automation
  2. Cloud computing
  3. Monitoring and alerting

Why this is incorrect: Numbering items that do not require a specific order, for example, general concepts.

Introductory text

  • Ensure the purpose of the list is clear. Introduce the text with a heading or complete sentence.
  • If you introduce a list with a heading, skip the explanatory text after the heading.
  • Avoid using a colon or period in the heading.

Correct

With heading:

Steps to Install XYZ
  1. Step One.
  2. Step Two.

With sentence:

Follow the steps below carefully to install XYZ.

  1. Step One.
  2. Step Two.

Incorrect

With heading + sentence:

Installation Steps

The following steps will guide you...

With sentence but no clear purpose:

The software installation involves several steps.

Why this is incorrect: Starting a list without a heading or an introduction leaves readers unsure of the list's purpose.

Capitalization

  • Begin each item in a list with a capital letter unless there's a reason not to, such as a command, which is always lowercase. 
  • If necessary, rewrite the list item so that all items begin with capital letters or all items begin with lowercase words.

Correct

Consistent capitalization

  • Download the application.
  • Install the application.
  • Launch the application.

Incorrect

Inconsistent capitalization

  • download the application.
  • Install the application.
  • Launch the Application.

Punctuation

  • Use consistently in the list and other lists within the same section.
  • Avoid using semicolons, commas, or conjunctions (like and or or) at the end of list items.
  • Only use a period at the end of the list items when they're complete sentences, even if the complete sentence is very short. If all items have three or fewer words, skip the period.
  • If the list is introduced by a sentence that ends with a colon, end all the items in the list with a period. The items should form a complete sentence when combined with the introduction sentence.

Correct

Complete sentences:

To secure your account correctly:

  • Enable two-factor authentication.
  • Regularly update software.

Short items without complete sentences:

Our priorities are:

  • Quality
  • Efficiency
  • Innovation

Incorrect

Incomplete sentences:

Improvements include:

  • Faster loading time.
  • Improved security.

Mixed punctuation:

Our priorities are:

  • Quality,
  • Efficiency;
  • Innovation.