Using tables in technical documentation
People read technical docs for a variety of reasons. These reasons can be broken down into two very broad categories:
- Reading to learn.
- Reading to get something done.
Users who are reading to learn are typically okay with reading paragraphs. They might want a general overview about a new topic or a refresher on a topic they haven’t thought about in a long time.
Users who are reading to get something done typically skim technical documents, looking for the specific piece of information they want. These users might want instructions on how to complete a task or decision criteria. Often, these users don’t have time to read paragraphs. They want something else.
A lot of people use lists for non-overview material. This is a good thing: lists break up text and make your content more scannable for users.
When to use tables instead of lists
Lists are good, especially when the list content is just doing one thing. For example, you might want to just list various use cases:
“You can use System A in the following use cases:
- Use case 1
- Use case 2
- Use case 3"
Sometimes, though, tables can be an even better choice than lists.
If you’re trying to do multiple things in a single list (for example, you might want to list different use cases and also describe which implementation approach to take for each use case), you might consider using a table instead to make your content more scannable and easier to digest.
For example, say you have a system that users can interact with in various ways depending on what they want to do. Putting this information in a list might look something like the following:
“Use the following list to determine how to integrate with System A according to your use case:
- If you want to use case 1, integrate with System A in way 1
- If you want to use case 2, integrate with System A in way 2
- If you want to use case 3, integrate with System A in way 3"
This list splits up the information and makes it scannable. However, there’s still quite a lot of repeated text in this short list. While the repeated text really isn’t a problem in such a short list, it could really bulk up the list if you needed to add additional things to each bullet point (for example, benefits, drawbacks, and links to integration instructions.)
Using a table could reduce some of this repetition. Putting the same information from above in a table might look something like the following:
“Use the following table to determine how to use System A according to your use case:
| If you want to... | Integrate with System A in... |
|---|---|
| Use case 1 | Way 1 |
| Use case 2 | Way 2 |
| Use case 3 | Way 3 |
Important caveat
Lists are always better than tables for numbered lists (for example, if you’re writing step-by-step instructions). Tables usually don’t do a good job of conveying chronology.
How to convert your paragraphs to lists and your lists to tables
Tables are good. But, I’ve found it’s often hard to start with a table: it’s often easier to write a paragraph or list and then convert it to a table.
When I write technical docs, I almost always create first drafts that contain lots of long, dense paragraphs. I’ve found this is the easiest way for me to get all of the information on the page. Once I have a few pages of wall-to-wall text, I skim the document and try to split things up into lists wherever it makes sense
Then, I skim the doc again and consider if I should convert any of my lists to tables.
(As part of my editing process, I also restructure sentences, cut out redundant information, clarify definitions, and a whole lot of other things. But that’s a story for another time.)
I’ve found that this broad three-step process helps me improve my docs by being more intentional about how readers are going to use my docs.