Lists (Ordered and Unordered)
Lists improve the readability and organization of information. Use them to break down complex instructions, features, or concepts into scannable pieces.
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 great for:
- Easy navigation.
- Quick scanning.
- Efficient comprehension.
Incorrect
Lists are great because they help users with navigation, make it easy to scan the document quickly, and they're also good for understanding complex information efficiently.
Unordered lists (bullets)
Use bulleted lists for items that share something in common but don't need to appear in a specific 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: This process is sequential. Use a numbered list instead.
Ordered lists (numbered)
Use numbered lists for steps or items that must appear in a specific order.
Correct
- Turn on the computer.
- Log into your computer.
- Open the browser.
Incorrect
- Importance of automation
- Cloud computing
- Monitoring and alerting
Why this is incorrect: These are general concepts with no required order. Use a bulleted list instead.
Introductory text
- Ensure the purpose of the list is clear. Introduce the list with a heading or a 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
- Step One.
- Step Two.
With sentence:
Follow these steps to install XYZ.
- Step One.
- Step Two.
Incorrect
With heading + sentence:
Installation Steps
The following steps guide you through the installation process.
With sentence but no clear purpose:
The software installation involves several steps.
Why the first is incorrect: A heading and an explanatory sentence together are redundant. Use one or the other.
Why the second is incorrect: The sentence doesn't tell the reader what to expect. It doesn't introduce the list's purpose clearly.
Capitalization
- Begin each list item with a capital letter unless the item is a command, which is always lowercase.
- Rewrite items if needed so all items begin consistently — either all capitalized or all lowercase.
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
- Apply punctuation consistently across all items in the list and all lists in the same section.
- Avoid semicolons, commas, or conjunctions such as and or or at the end of list items.
- Use a period only when list items are complete sentences. If all items have three or fewer words, omit the period.
- If the list is introduced by a sentence ending with a colon, end each item with a period. Each item should complete the introductory sentence.
Correct
Complete sentences:
To secure your account:
- Enable two-factor authentication.
- Update your software regularly.
Short items without complete sentences:
Our priorities are:
- Quality
- Efficiency
- Innovation
Incorrect
Incomplete sentences with periods:
Improvements include:
- Faster loading time.
- Improved security.
Mixed punctuation:
Our priorities are:
- Quality,
- Efficiency;
- Innovation.