Tables in documentation: when they help and when they get in the way

Tables are one of the first things I look at when I edit documentation. Sometimes a table is the clearest part of a page. Other times it's where the page falls apart: cells full of paragraphs, a column nobody needs, or a sequence of steps forced into rows.

Here is how I decide whether a table should stay, and what I change when it does.

A table is for comparing

A table works when the reader wants to compare several items across the same set of attributes. Plans and their limits, configuration options and their defaults, API parameters and their types. The reader's eyes move across a row or down a column, and the grid makes that easy.

| Option    | Type    | Default | Description                         |
|-----------|---------|---------|-------------------------------------|
| `timeout` | integer | `30`    | Seconds to wait before giving up.   |
| `retries` | integer | `3`     | How many times to retry on failure. |
| `verbose` | boolean | `false` | Print each request to the console.  |

Every row answers the same questions in the same order. That's the test I use: if the rows don't share the same columns naturally, it probably isn't a table.

Steps don't belong in a table

A common pattern is a table with "Step" and "Action" columns. It looks organised, but it adds nothing a numbered list doesn't already do, and it's harder to read on a narrow screen. Lists also give each step room for a short note or a code block, which a table cell handles badly.

1. Open **Settings** and select **API keys**.
2. Select **Create key**.
3. Copy the key and store it somewhere safe. It's only shown once.

Keep cells short

If a cell needs more than a sentence or two, the content usually belongs somewhere else. I move longer explanations into the text below the table, or into a separate section, and keep the cell to a short summary. A table full of paragraphs forces the reader to scroll sideways or read text squeezed into a narrow column.

Many Markdown flavours, including GitHub Flavored Markdown, don't support lists or multiple paragraphs inside a table cell anyway, which is a useful hint.

Make the headers do the work

Column headers are where the reader looks first, and some screen readers announce them together with each cell. So I make them specific:

• Put units in the header, not in every cell: Timeout (seconds) instead of 30 seconds in each row.
• Match the name used in the code or on screen. If the setting is called retries, the header doesn't say "Attempts".
• Avoid empty headers. A blank first header above a column of names makes the table harder to follow when it's read aloud.

Don't leave cells empty

An empty cell can mean "no", "not applicable", "unknown" or "someone forgot". The reader has no way to tell which. I write the actual answer, such as "None", "Not supported" or "Not applicable", and I use the same wording throughout the table.

Order the rows on purpose

Alphabetical order is fine when the reader is looking something up by name. When most readers only need two or three rows, I put those first, or I split the table into "common options" and "advanced options". Either way, I want the order to be a choice, not whatever order the rows were added in.

Watch out for pipes and alignment

Two small Markdown details catch people out. A literal pipe character inside a cell breaks the column structure unless it's escaped, even inside inline code in GitHub Flavored Markdown:

| Operator | Meaning    |
|----------|------------|
| `a \| b` | a or b     |

And colons in the separator row control alignment. Numbers are easier to compare when they're right-aligned:

| Plan  | Users | Storage (GB) |
|:------|------:|-------------:|
| Free  |     1 |            5 |
| Team  |    10 |          100 |

One last test

My last step is to read one row from left to right and ask whether it makes sense as a sentence: "The timeout option is an integer, defaults to 30, and sets the seconds to wait." If a row can't be read that way, the columns are probably mixing different kinds of information, and the table needs another edit.

Comments

[Adam Lewis]

"Put units in the header, not in every cell" is wrong on this point. A header gets read once on the way in and then it's off the top of the screen while the reader is down in row nine with a number and no idea what it means. The cell that says 30 seconds costs a few characters and never leaves the reader guessing.