⇐ Sentences ⇐ ⇑ Course overview ⇑ ⇒ Paragraphs and tables ⇒
Lists
If it’s a list, make it a list
Part of the reader’s cognitive load is figuring out what the writer is doing in any given sentence. Are they stating an opinion? Making a comparison? Describing something? How much will I learn from this sentence?
Replicants are the ideal workforce for off-planet installations because they are inhumanly strong, guaranteed disease-resistant, well-trained in a variety of technologies, and too short-lived to require pensions.
But readers don’t need to figure out lists because the format carries meaning. They know how they work. You can identify a list and recognize its components even in a language you can’t read.
So if a long sentence is really a list, your reader will experience less cognitive load if you make it look like one.
Replicants are the ideal workforce for off-planet installations because they are:
-
Inhumanly strong
-
Guaranteed disease-resistant
-
Well-trained in a variety of technologies
-
Too short-lived to require pensions
|
Note
|
By definition, a list must have more than one item. Sentences with three or more items should default to being lists. When there are two items, choose whichever format is clearest to the reader. And Rule Zero applies: do what helps your reader first, follow the rules second. |
Bullet or numbered?
The kind of list you use tells your users how important item order is. Only use a numbered list if the order of items matters. Otherwise, use a bullet list.
| Bullet list | Numbered list |
|---|---|
The list still makes sense if you rearrange the items. |
Shuffling the list items destroys the logic or meaning. |
Aloy can override the programming on several creatures:
|
Let’s do the Time Warp again:
|
|
Note
|
Sometimes it’s tempting to use a numbered list so that you can refer to individual list items lower down in your text (for example, to explain them at greater length). This is a bad idea:
A better way is to make a key term in the list item bold, then use that bold term in the text that refers back to the list. That way the linkage is natural, logical, and won’t be broken by adding or rearranging items. |
Put shared information in the introduction
Vor noblemen do certain things when they reach adulthood:
|
Vor noblemen must do certain things when they reach adulthood:
|
Lists do two things in technical writing:
-
They explicitly set out a collection of similar things.
-
They implicitly draw attention to the differences between those things.
In other words, every item on a list shares something with the other items (or it wouldn’t be in the list) and has its own distinct identity (or it would be a duplicate).
To make the content of each item as distinct as possible, move anything that all the items have in common to the introductory sentence. Even though the items in the first list are phrased a little differntly, you can see that they’re about things that Vor nobles must do. Moving that "must" into the introduction allows the reader to see each element as different.
|
Note
|
This rule is about the content of the introduction, not its formatting or grammar. Some style guides require that the list introduction be a sentence. Others don’t express a preference. |
Make list elements consistent
The second step in distinguishing your list items is to eliminate differences in how they are written. Inconsistent grammar and phrasing distract your reader from the ways the content of the list items differs.
There are rules for what you can have in your quarters:
|
The following possessions are forbidden in crew quarters:
|
The first example has both positive and negative elements. Some of the items are complete sentences and others aren’t. This chaos makes it difficult to create a clear introduction. Crew members can have lots of things in their quarters, including furniture, roommates, air, and parties. What is this list really talking about?
Putting all of the list items into the same form emphasises their content differences. It also leads to a clearer introductory sentence.
Formatting list items
The third part of emphasizing content differences between list items is the most superficial: formatting the items consistently. How you format the items depends on your style guide. If you don’t have one, this is a good approach:
Capitalization: Start each list item with a capital letter. Otherwise, if some words are naturally capitalized and some aren’t, the list looks ragged.
The broom was overloaded with cargo and passengers:
|
The broom was overloaded with cargo and passengers:
|
Punctuation:
-
If list items are basically sentence-shaped, finish each item with a period.
-
If list items are single words or groups of words, don’t put periods at the ends of any of them.
Either:
|
Or:
|
But not:
|
Do not punctuate your list items like they’re a sentence falling down the page like a waterfall.
This kind of list is hard to maintain well. Every time you add to, delete from, or rearrange it, you have to remember to update the punctuation.
|
Note
|
Consistency is more important than any of these rules. If an existing document punctuates lists one way, keep doing that, even if it breaks the rules. Most readers aren’t aware of the rules. But they may notice if your lists look wildly different. |
Grouping list items
There’s a limit to human attention. Your readers can only take in so much information before they stop reading and start just looking. The classic theory is that you can take in between 5 and 9 equivalent items (7 ± 2, also known as Miller’s Number). Although human memory is actually more complicated, lists longer than about 7 items are less effective than shorter ones.
However, this memory limit is recursive. Readers can understand a certain number of sublists, each with a certain number of elements. In other words, you can get more information into your reader’s head if you break it into chunks.
Bullet lists: categories and items |
Numbered lists: alternatives or sub-steps |
Minecraft flowers come in many colors:
|
How to tame a dragon:
|
-
Bullet lists can be broken up into sub-categories. Which sub-category you use (Minecraft flowers by color? by biome?) depends on what you’re writing, who your audience is, and what you want them to focus on.
-
Instructions can be broken up into sub-processes, which are also numbered lists. This can help readers by giving them intermediate goals.
-
Instruction lists can also have bulleted sublists with alternative methods of performing the step.
Instructions
Start with the user’s goal
To use your SecUnit:
|
To defend the base during an attack:
|
If you’re writing about a tool or system, you may be tempted to give the reader instructions on using that tool. You’re sending a Security Unit (SecUnit) to people on a far-off mining planet. You want to tell them how to use the SecUnit.
But your readers aren’t trying to use the SecUnit just because. They’re not going to post Achievement unlocked: Use the SecUnit on social media. They have a real-life goal in mind, something that matters to them. Your tool or system is just the means to that end.
You have to step out of your own context and into theirs. What is the real problem they’re trying to solve? The mining base is under attack. The SecUnit is the tool for defending the base. So start your instructions with the problem your readers are trying to solve, the goal they’re trying to achieve.
Three kinds of step
Instructions can contain three kinds types of step:
-
Required step: Your reader must do this.
-
Conditional step: If the condition is true, then the reader must do this. Always put the condition first so your reader knows early on whether to pay attention to the step.
-
Optional step: Like a conditional step, this is something that not all readers have to do. The step may be completely optional. Or it may be a conditional instruction whose condition is too complicated for a simple if clause.
How to evade a sandworm in the deep desert:
-
Optional: Activate a thumper to distract the worm. ← Optional
-
Walk with an uneven rhythm. ← Required
-
If there are rocks nearby, go toward them. ← Conditional
Picture your reader on the desert planet Arakkis, also known as Dune. They’ve just crashed their flyer in the deep desert, which is where the sandworms roam. What do they do now?
There are two important things to know about sandworms:
-
If they catch you, they will eat you.
-
They are attracted to rhythmic noises.
So your reader absolutely must walk with an uneven rhythm. Otherwise their footsteps will attract a worm. If there are rocks nearby, they should go toward them, because sandworms an’t get into rock formations.
Should they activate a thumper, which is a device that gives out a rhythmic thumping noise after a short delay? Well, that’s complicated.
-
Do they have a thumper with them?
-
What kind of sand are they on? Will the vibrations carry or be muffled?
-
Are they able to move quickly enough to get away from the thumper before it starts thumping? If not, a thumper is less of a distraction and more of a sandworm dinner bell.
Realistically, your reader is going to need a separate section of your documentation that explains thumpers and how to use them.
|
Note
|
The correct way to signal an optional step is to start it with Optional:. Many people write Optionally, but that’s not grammatically correct. |
Use "you" forms
|
Writers can be tempted to use we forms in instructions in order to sound friendlier. Unfortunately, this comes across as talking down to your audience. It sounds a little like you’re a kindergarten teacher telling a bunch of kids, "Now let’s clean up the playroom".
Instead, use you forms. This includes both using simple commands (which are implicit you forms) and specifically saying you and yours when needed.
It’s shorter and gives the reader some dignity.
|
|
Write in the present
After you take the red pill, the Matrix will eject you.
Normally, if you write about the result of something that happens in the present, you use future verbs.
But instructions aren’t normal, because as the reader moves forward through them, their "present" changes. And once those readers are at step two, they’re in the "future" that you described after step one. How do you move them even further through time? English doesn’t have future-of-the-future verb forms.
Instead, when you’re writing instructions, keep your readers in an eternal present.
After you take the red pill, the Matrix ejects you.
|
Note
|
If something is in the real, verifiable future, like in the year 2050, go ahead and use the future tense. The eternal present is for timeless information. |
Exercise
To practice what you’ve just learned, do the list and instruction exercise.
⇐ Sentences ⇐ ⇑ Course overview ⇑ ⇒ Paragraphs and tables ⇒