As part of my sporadic series on documenting software, I wanted to devote a posting to lists, because they play a much larger role in tech writing than they do in typical prose. People reading a chapter of software documentation are less likely to read it from beginning to end than they are to skim it looking for an answer, and if the question is “how do I accomplish task X”, the answer is probably a multi-part answer. When the instructions for task X are broken up into separate list items, they’re easier to find and easier to follow—after carrying out step 3, it’s easier to go back and find step 4 if it’s indented with a big “4” in front of it than if it’s in the middle of big dense paragraph.

The two basic kinds of lists, both so common that word processing programs usually offer tool bar buttons to quickly create each, are bulleted lists and numbered lists. The former is sometimes called an “unordered list,” giving us the ul element name used by HTML to create them, and numbered lists are often called “ordered lists”, giving us the HTML ol element.

Sometimes people use one when they should use the other, especially in PowerPoint presentations. The test for which to use is simple:

1. Think about whether changing the order of your items would cause real problems. It may improve your presentation to save a certain point for last, but if that point came earlier and your audience still got all the information that they need, then that’s not a real problem. If you tell your readers to pour oil into the engine before tell them to remove the cap, that’s a real problem.

2. If the ordering really matters, make it a numbered list. Numbered lists are for giving directions, whether you’re telling someone how to drive to your house, how to install a piece of software, or how to perform a particular task with that software.

I’ll admit, that was a pretty contrived example of a numbered list. Lists with only two items, especially numbered lists, are usually not worth formatting as lists. (There are more contrived examples to come.)

Bulleted lists are popular for for:

• Listing issues to keep in mind when considering a particular topic.

• Highlighting the good points of something, which is why bulleted lists are popular in marketing literature.

• Naming the bad points of an entity or course of action.

• Showing short examples of something.

• Identifying future issues to think about that build on what the reader has seen so far.

In the sample bulleted list above, note that none of the list items are complete sentences and that they all end with a period. If all the items in a list are complete sentences, or if none ends with punctuation, that’s fine, but remember to be consistent throughout a given list. I once saw a bulleted list on a resume from someone applying for a tech writer job in which some items ended with periods and some didn’t. If the applicant had wanted to be anything but a tech writer (or perhaps a proofreader or copy editor) this would have been acceptable, but in this case it wasn’t. We didn’t call him in for an interview.

You don’t have to limit each list item to one phrase, sentence, or even one paragraph. For example:

• This first list item in this numbered list has two paragraphs.

  Additional paragraphs in a list item let you give more background on a particular point without having a large, dense paragraph as your list item. If you put too many paragraphs in a single list item, though, that section of the list looks less and less like a list, which confuses the reader.

• If the content that you’re writing must be converted from one format to another, make sure that these multi-paragraph list items don’t get mangled. Some conversion programs assume that every paragraph in a list is a new item.

Another advanced technique, which is pretty ubiquitous in PowerPoint presentations, is nested lists.

• Inside a numbered list item:

  • A nested numbered list can break down a step from the main list into its constituent parts.

  • A nested bulleted list can highlight certain issues to keep in mind when executing the step.

• Inside a bulleted list item:

  • A numbered list points out issues related to the list item where the order matters.

  • A bulleted list breaks out the point into subissues.

(I warned you that many of these examples would be contrived.) I didn’t pick the separate bullet characters for the list and sublists above. Because I put a ul element inside of another ul element’s li list item element when creating this HTML, browsers change the bullet automatically to show you the different nesting levels. To change the nesting level of list items in a word processor, select them and click the indent or outdent button on the toolbar.

HTML offers a third type of list known as a definition list. Instead of demonstrating it, I’ll point you to the list of eight list types offered by DocBook, which itself is a definition list. The DocBook DTD includes a wider choice of list types because it offers the ability to address technical documentation issues at a much finer-grained level of detail. It’s worth reading through the list describing the eight types.

If you think that lists are not something to get passionate about, you’re absolutely right. They’re a tool for technical communication. I can’t finish up, though, without mentioning Information Mapping®, which has had an intermittent influence on tech writing over the years. Robert Horn, a psychologist at Columbia University, developed some theories, a methodology, and a company dedicated to more efficient organization and communication of information. If I can oversimplify their approach, I would say that whenever you can break something down into a list, you should. They call the process of breaking down information “chunking”, and I must say I do like the use of “chunk” as a verb. There’s a wide-eyed, evangelical zeal to the serious devotees’ belief that everything can be information mapped—when a former co-worker took a course in Information Mapping, the certificate he received for doing so was formatted as an Information Map. Of only five questions on the company’s FAQ, one of them is titled “Handling resistance to mapping.” All your information are belong to us!

As a result of some serious quantitative research, there is certainly some value to Information Mapping, and a tech writer can learn a lot from it without drinking the Kool Aid. If their approach to modular content architecture didn’t have a direct influence on DITA, it certainly had a strong indirect influence, because serious tech writers had been aware of it for years.

I can’t resist closing with a bulleted list:

• Take a closer look at how lists are used in the documentation you see and what choices their authors made in presenting them.

• If you explore the more advanced possibilities such as multi-paragraph list items or nested lists, check that conversion routines converted them properly. People who write these routines may not have considered the less simplistic possibilities.

• If you’re doing more complex technical writing using the DocBook DTD, get to know its other list types and make sure that your production routines can handle any that you use. Lots of the DocBook DTD is optional, and conversion routines often don’t address everything that may come up.

3 Comments

By John L. Clark on June 1, 2006 1:55 PM

What about using numbered lists in order to give each item in an otherwise unsequential list an identity (even if only for the visual presentation of the current version of the list)? “I want to make statement `foo’ about item 7 in that list.”

1. Should we use lists like this?
2. How does this approach integrate with your suggestions above?
3. How can we differentiate between numbering lists for reference and numbering lists for sequence, first to our readers and second in our markup?

By Bob DuCharme on June 1, 2006 9:14 PM

Good point: the use of numbers to provide an addressing system. I’d be more inclined to do what contracts and laws do (although they also use regular Arabic numerals): use letters or upper- or lower-case roman numerals to make it easier to reference specific paragraphs. Of course, sometimes the order does matter in those and sometimes it doesn’t, and they often use these alternate ways to identify nesting levels, just like the different bullets shown in my nested bulleted list.

I just learned about the list-style-type CSS property for the ol element, which makes this possible. As to differentiating between the two types you describe in the markup, the use of a class attribute to trigger the use of the list-style-type would do that–just pick a good name for the attribute value!

As I explained at http://www.oreillynet.com/pub/wlg/4772, I put IDs on all my block level elements so that I can link to them. For example, this links to the third item in the first bulleted list above.

By karl on June 4, 2006 8:28 PM

There’s an interesting about the nature of XML and its infoset, it is an ordered tree. What does that mean? It means that an “unordered list” is really a semantic definition and not the nature of XML itself, then at the root level of the markup, there is no difference between ul and ol. There are exactly the same by nature.

The real difference is made when a user agent (browser, authoring tool, bot, indexing engine, semantics engine) has been specifically programmed to make sense of it. This is one of the big trouble of the Web right now. Most of the browsers are not semantics tool but (CSS) renderers with very little semantics capacity.

A graph is often not ordered at all, so lists in RDF have no sequential reading except if you create a mechanism which says this has to be read in this order.