Lists and Bullets — Structuring Information for Scannability in Technical Documentation

In this tutorial, you will learn about Lists and Bullets. We cover key concepts, practical examples, and best practices to help you master this topic.

Lists and bullets transform dense paragraphs into scannable content. They help readers find key information quickly and understand relationships between items. Properly formatted lists are one of the most effective tools in technical writing.

In this lesson, you will learn how to use different list types appropriately and format them for maximum readability.

What You'll Learn

You will understand when to use each list type, format lists for readability, and avoid common list formatting mistakes.

Why It Matters

Readers scan documentation before reading it. Lists draw the eye and convey information quickly. Poorly formatted lists confuse readers and waste their time.

Real-World Use

DodaTech converted dense technical paragraphs into structured lists throughout the DodaZIP documentation. Time to find specific information decreased by 30 percent in user testing.

flowchart LR
  A[Content] --> B{Sequential?}
  B -->|Yes| C[Numbered List]
  B -->|No| D{Related Items?}
  D -->|Yes| E[Bullet List]
  D -->|No| F{Terms with Defs?}
  F -->|Yes| G[Definition List]
  F -->|No| H[Paragraph]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Numbered Lists

Use numbered lists for sequential steps where order matters. Each step should start with an imperative verb. Numbered items tell the reader that order is important.

Keep numbered lists focused. If a step has sub-steps, indent them as a secondary list. Avoid mixing numbered steps with bullet items.

Each numbered item should contain one action. If a step says install the package and configure the settings, split it into two steps.

# Good numbered list
1. Install DodaZIP
2. Create a compressor instance
3. Compress your file
4. Verify the output

# Bad: Steps too large
1. Install DodaZIP and create a compressor instance
2. Compress your file and verify the output

Bullet Lists

Use bullet lists for non-sequential items where order does not matter. Keep bullet items at a consistent grammatical form.

Introduce bullet lists with a complete sentence ending in a colon. Each item should complete the introductory sentence where possible.

Keep bullet items concise. If an item needs multiple sentences, consider splitting it into a sub-list or a short paragraph.

# Good bullet list
DodaZIP supports three compression algorithms:
- Gzip: Best compression speed
- Bzip2: Better compression ratio
- XZ: Best compression ratio, slowest speed

# Bad: Items are complete sentences in an otherwise fragment list
Supported algorithms:
- Gzip offers the best compression speed.
- Bzip2 provides a better compression ratio.
- XZ delivers the best compression ratio.

Common Mistakes

1. Wrong List Type

Using numbers when order does not matter. Using bullets when steps must be sequential.

2. Inconsistent Punctuation

Some items end with periods, others do not. Either all items end with periods or none do. Complete sentences get periods. Fragments do not.

3. Capitalization Inconsistency

Some items start with capital letters, others lowercase. Be consistent within each list.

4. Lists Too Long

A list with more than 10 items is hard to scan. Break long lists into categories.

5. No Introduction

Lists without introductory text confuse readers. They do not know what the list represents.

6. Nested List Overuse

More than two levels of nesting becomes confusing. Restructure content to avoid deep nesting.

7. Parallelism Missed

Items in the list use different grammatical forms. Use parallel structure for all items.

Practice Questions

1. When should you use a numbered list?

When the order of items matters. Numbered lists are for sequential steps and ranked items.

2. When should you use a bullet list?

When the order does not matter. Bullet lists are for sets of related items.

3. How should you introduce a list?

With a complete sentence ending in a colon. The sentence should explain what the list contains.

4. What punctuation rules apply to list items?

If all items are complete sentences, end each with a period. If items are fragments, do not use periods. Be consistent.

5. Challenge: Take a dense paragraph of at least 150 words and convert it to a properly formatted list structure. Choose the right list type and format items correctly.

FAQ

Mini Project

Audit a documentation page for list formatting issues. Identify wrong list types, inconsistent punctuation, capitalization errors, missed parallelism, and missing introductions. Fix every issue you find.

What's Next

Next: Notes, Warnings, and Tips