Advent of Technical Writing: Lists

This is the seventh post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

When I edit technical content, I often see two extremes when it comes to lists: not using them at all, even when lists are an appropriate way to convey information given the piece, and using them too much. The crux of finding a balance is knowing when to use lists. Therein lies a question: when are lists useful?

I want to talk about lists in the context of ordered or unordered and unordered lists. Ordered lists, which start with numbers, should be used to convey sequential information (i.e. actions to take in a product). Unordered lists, which start with bullet points, can convey any related points

Lists are useful when you have a series of points that you want to convey and highlight. Rather than list the points you want to make with commas -- and potentially end up with a paragraph that is difficult to read, depending on how long each point in the list is -- you can separate out each point.

I like lists because they:

• Are easy to skim;
• Can improve reading comprehension, and, as a result;
• Give you a tool to highlight key pieces of information

Let's talk through some scenarios where lists can be helpful.

Lists in product documentation

Lists are easy to skim, allowing a reader to easily digest information. This is especially important in product instructions and documentation.

Consider the following introduction to a feature called Health Check in Roboflow, a computer vision platform:

Health Check shows a range of statistics about the dataset associated with a project. You can see the following pieces of information:

• Number of images in your dataset;
• Number of annotations;
• Average image size;
• Median image ratio;
• ...

Health check offers nine pieces of information that someone can use to analyze a dataset. Each piece of information is listed in a bullet point (the snippet above is edited for brevity).

A paragraph containing this information would be verbose; a section with a sentence devoted to each would cause the page to balloon in size, without clear value to the reader. Indeed, the value to the reader is knowing what the feature is, how it can help them, and how to access it. The bullet points play a key role in educating the reader what the feature (health check) offers. By virtue of the list enumerating features, conveys information needed to evaluate how the feature can help them.

You can also use bullet points to list steps, like Supabase does in the "Project setup" section that is embedded across several tutorials on their site (example):

Let's create a new Postgres database. This is as simple as starting a new Project in Supabase:

1. Create a new project in the Supabase dashboard.
2. Enter your project details. Remember to store your password somewhere safe.

Your database will be available in less than a minute.

Finding your credentials:

You can find your project credentials inside the project settings, including:

• Database credentials: connection strings and connection pooler details.
• API credentials: your serverless API URL and anon / service_role keys.

Here, we ahve two lists. The numbered list enumeate product actions that you should follow. The bullet points highlight two key pieces of information you need: database and API credentials.

Lists in blog posts

I sometimes lists to explain long code snippets. If a post contains a lot of code and text, I find using numered lists as an effective way to introduce variation in how explanations are preesnted.

Consider this description, taken from a code snippet on a guide I wrote on using Optical Character Recognition with the Roboflow Inference product:

In this code, we:

1. Use a fine-tuned model to identify the container number in an image, then;
2. Make a web request to the OCR endpoint to retrieve the text in the image.

You will need to replace two values in the code above:

1. image.jpg: The name of the image on which you want to run OCR, and;
2. API_KEY: Your Roboflow API key. Learn how to retrieve your Roboflow API key.

I used numbered points twice: first to list what the code does, then to highlight what values the reader needs to replace.

Balance

Indeed, like using a balance of short and long sentences helps make writing more cohesive, using lists throughout a post makes it easier to comprehend content.

With that said, you should use lists conservatively. In this article, I used lists once outside of the example excerpts (which had to include lists because the post this blog post, unlike any other I have written, is about lists!). I find that I use lists no more than a few times in a guide.

You should avoid using lists as the primary method you use to explain concepts. Lists can improve readability, but a long list of bullet points is confusing; finding the information one needs will be difficult.

How do you find balance? Practice. If you write content that contains a lot of lists, consider if some of them could be paragraphs. Some lists only need a bit of revision to be turned into a fully-formed paragraph. Conversely, if you have a dense paragraph that explains a code snippet, it may be worth either dividing into several paragraphs or, if there is not too much information, using ordered or unordered lists.

Join me tomorrow for another technical writing tip!