Writing Lists

    By: Jonathan Gennick on Dec 11, 2018

    Writing Lists_header image.png

    Lists are an essential aspect of technical writing. They are easy to create, yet many authors go wrong and end up with suboptimal presentation of their content. Here are some things to think about next time you write a list into a blog post or piece of technical documentation:

    • Type of list
    • Introduction
    • Parallelism

    Or perhaps instead, here are the precise steps to follow next time you write a list into a blog post or piece of technical documentation:

    1. Choose the type of list
    2. Introduce the list
    3. Write the items in parallel form

    What’s the difference? Read on to find out.

    Choosing the Type of List

    Fundamentally, you can either number the items in a list or not. The common dichotomy is one of a bulleted versus a numbered list. Bulleted lists describe bags of items. Numbered lists describe steps in a process. Most lists that I see in technology books should be bulleted. You might be surprised at how often I see manuscripts in which process steps have bullets and bag items have numbers.

    Following is an example of the wrong approach. It’s a list of items commonly found in hardware stores. The list should not be numbered, because the items are not describing steps in a process:

    1. Bolts
    2. Nuts
    3. Washers
    4. Wood screws
    5. Sheet metal screws
    6. Hose clamps

    Items in a hardware store are bag items. They should be given in a bulleted list, like this one:

    • Bolts
    • Nuts
    • Washers
    • Wood screws
    • Sheet metal screws
    • Hose clamps

    Ask yourself this question: Are you describing a process? Write a numbered list if the items describe steps in a process. Otherwise, write a bulleted list. This is good general advice that will serve you well in business and technical writing.

    Introducing a List

    Never let readers encounter a list without your first having introduced the list. Think of the concept of class as used in programming languages like C++ or Java. A list is a class, and each list item therefore is a member of the class.

    • Precede each list with a specific introduction
    • Say clearly and plainly what each item in the list represents
    • Never rely on the context of your writing to convey to readers the intent of a list
    • Be explicit

    Oops! The preceding list is a precise example of what not to do. Where is my introduction? Let me backup and try again….

    Never let readers encounter a list without your first having introduced the list. Think of the concept of class as used in programming languages like C++ or Java. A list is a class, and each list item therefore is a member of the class. Following are some good practices to help ensure readers understand what the class is, and what each list item represents:

    • Precede each list with a specific introduction
    • Say clearly and plainly what each item in the list represents
    • Never rely on the context of your writing to convey to readers the intent of a list
    • Be explicit

    Having introduced a list, it’s up to you to ensure that each item in the list is a proper member of the class. Here is a list of common kitchen appliances that is an example of a list gone wrong:

    • Blender
    • Toaster
    • Vacuum cleaner
    • Center Island for Food Preparation
    • Ample Cupboards
    • Pots and Pans

    Is each item in this list an appliance? And of the appliances, are they all kitchen appliances? Only the first two list items fit the class. A list of common kitchen appliances would include:

    • Blender
    • Toaster

    The other items are not kitchen appliances. If you want them in the list, then you must change the introduction such that the class of list includes those other items. A better approach might be to treat those other items in separate lists.

    If you find yourself badly wanting to mix items in a list that don’t belong well together, take that as a sign that you should step back and look at the bigger picture around the passage you are trying to write. You may need to rethink the overall approach in the blog post, article, or book chapter that you are writing.

    Stepping back and rethinking your content is difficult and painful, but always pays off. I wrote content for this very article that didn’t fit well due to parallelism issues, and after much pain and many tries at rewriting to force things to work, decided to remove that content and save it for a future article.

    Creating Parallel Form

    The term parallelism is used in writing to describe a desired consistency in form, style, and structure. Let’s revisit kitchen appliances. Here’s a somewhat longer list of common kitchen appliances:

    • Blender
    • Toaster
    • Some coffee drinkers have pod-based coffee makers
    • Microwave ovens
    • You might even have a warming oven
    • Avocado-colored appliances

    These items are not all in the same grammatical form. The first two items are simple nouns. The third item is a phrase and breaks the pattern of parallelism. The list is inconsistent.

    Following is a slightly improved version of the list, with the phrases removed and replaced by nouns:

    • Blender
    • Toaster
    • Coffee makers
    • Microwave ovens
    • A warming oven
    • Avocado-colored appliances

    Notice that two of the nouns are plural. Consistency is the goal. Either make all the nouns plural or make them all singular. Here’s a new list of common kitchen items written with plural nouns:

    • Blenders
    • Toasters
    • Coffee makers
    • Microwave ovens
    • A warming oven
    • Avocado-colored appliances

    That “A warming oven” item is a problem. Maybe I’m trying to convey the sense that a kitchen is unlikely to have multiple such ovens. No matter! Parallelism must be respected. If I want to convey to readers that certain items are unlikely to be found in multiples, then I need to find some other way to convey that information. I can reorganize my content, create separate lists, or touch on the issue in a paragraph following my list. For now, I’ll just correct the parallelism of that one item. Here is my updated list of common kitchen appliances:

    • Blenders
    • Toasters
    • Coffee makers
    • Microwave ovens
    • Warming ovens
    • Avocado-colored appliances

    This brings us to the final item in the list. That item “Avocado-colored appliances” breaks parallelism, but before that it doesn’t even belong in the list at all—because it breaks the class. The list introduction followed by the pattern of the earlier items make clear that each item in the list is a type of appliance. Avocado is a color, not an appliance type, so the item gets thrown out and our final list of common kitchen appliances looks like this:

    • Blenders
    • Toasters
    • Coffee makers
    • Microwave ovens
    • A warming oven

    We can talk about avocado and other colors in some other paragraph. The need to remove mention of that color from the list suggests we either don’t need the item at all, or we need to step back and think carefully about where in our content we will talk about colors. Deleting the item looks easy in this article, but a simple edit like that can force a lot of rethinking on the part of an author. That rethinking is always for the good.

    A final aspect of parallelism is when a list relates to the structure of the overall content in the blog post, article, or book chapter that is being written. Remember my list from the start of this article? Here is that list again:

    • Type of list
    • Introduction
    • Parallelism

    Now look back at my section headings and see how I covered my subtopics in the same order as they appear in the list. Doing so is good parallelism. I brought up three aspects of list writing and addressed them in the same order. Good parallelism brings consistency and clarity to your content, helping your readers to follow your discussion and absorb your message. That’s what good communication is about.


    JonathanGennick-150x150.pngJonathan Gennick is the Apress editor responsible for the IOUG Press, a cooperative publishing arrangement between Apress and IOUG with the aim of providing the very best in content for IOUG members and other Oracle professionals. Learn more at www.ioug.org/iougpress.

    Released: December 11, 2018, 12:34 pm | Updated: December 11, 2018, 12:43 pm
    Keywords: IOUG Press Corner | Website | how to write a list | IOUG Press | IOUG Press Corner | technical writing tips | Writing Tips


    Copyright © 2019 Communication Center. All Rights Reserved
    All material, files, logos and trademarks within this site are properties of their respective organizations.
    Terms of Service - Privacy Policy - Contact

    Independent Oracle Users Group
    330 N. Wabash Ave., Suite 2000, Chicago, IL 60611
    phone: 312-245-1579 | email: ioug@ioug.org

    IOUG Logo

    Copyright © 1993-2019 by the Independent Oracle Users Group
    Terms of Use | Privacy Policy