Steps of an algorithm

Whether you're writing about technology, gaming, or a recipe for your favorite pie, it's likely that you are listing a series of steps for your reader to follow. Here are a few principles to keep in mind when you're listing tasks for your reader.

Order matters

There are two kinds of explicit lists: ordered and unordered lists. An ordered list gives each item a number to provide a sequence, and the unordered list uses bullet points or similar characters to indicate items that don't have a particular order.

When you're listing steps that must be executed and completed in a specific order, use a numbered list. Humans recognize ascending numbers as a sequence, and follow each step from lowest to highest. Were you to change the order of an ordered list, the outcome of that list would change.

Here's an obvious example:

1. Fill the basin with water
2. Place baby in basin
3. Wash the baby
4. Remove baby from basin
5. Throw out the bathwater

For obvious reasons, it's vital that step 5 happens last.

An unordered list can be rearranged with no effect on outcome. Because there's no implied sequence, unordered lists are often used as manifests. For example, to wash a baby, you need:

• Baby
• Basin
• Bathwater

The order you gather these assets doesn't matter, as long as you have all three of them before starting the task.

Mental burden

Not everything in a document needs to be in a sequence, even when order matters. Readers understand that you intend for them to start at the beginning of the document and read to the last page. There's an implied order to the document.

Structuring a long document as one big ordered list may accurately reflect that the entire document represents a sequential process, but it doesn't give your reader time to relax.

When you follow instructions, part of your mental energy gets reserved for keeping in mind previous steps, and that you have some number of steps left to go before the process is complete. Maybe you're a little concerned that the instructions are wrong, or that you've done something wrong. There's a mental strain to following instructions, so it can be discouraging when an entire document passes itself off as an unbreakable algorithm.

Instead, recognize groups of tasks that can be done in isolation. In computer code, that's called a function or a method. Separate major methods with context about what the reader is about to do, or with instructions in a conversational tone.

Here are instructions on how to paint a plastic action figure:

To paint a model, first gather your paint brushes, paints, a palette, and a cup of water. Place the model on your workbench.

For each color you want to apply:

1. Dip your brush in the pot of paint
2. Dab the paint onto your palette and then wet your brush with water
3. Mix the water from your brush with the paint on the palette to thin the paint
4. Brush the paint onto the model

After applying the paint to the model, allow the paint to dry for several minutes. In the meantime, wash your brush so it's clean of residual paint.

Most of the process described in the sample painting documentation is sequential. You have to gather your supplies before actually painting, but it's a one-time setup, so I wrote it as an introductory paragraph.

I used a numbered list for the actual painting process because it describes one algorithm that can be reused as many times as necessary to complete the paint job.

The final paragraph could arguably be part of the painting "algorithm," and there's an argument that it should be. After all, I wouldn't want my reader to paint something black, and then try painting white without cleaning the brush first. However, the numbered sequence is a self-contained sequence that could happen several times with just one color of paint, depending on how much paint is required. The final paragraph is its own process because it happens after the repetitive act of reloading the brush and applying it to a model.

Condensing steps

Following instructions in documentation takes faith and patience. The reader must have faith that you, the author, have provided accurate instructions that are sure to work. The reader must also be patient enough to step through your instructions, carefully following every step in detail, until the end. When a reader sees too many steps, it forces the reader to choose whether to invest in following it through.

To build confidence for your reader, though, you can adjust the number of steps in a sequence. One way to do that is to break your algorithm into isolated methods.

The other way is to adjust how much information you put into each step. Here's the five-step instructions on how to avoid throwing a baby out with the bathwater, reduced to three steps:

1. Fill the basin with water
2. Place baby in basin and wash the baby
3. Remove the baby from the basin, and then throw out bathwater

The steps are exactly the same, but for the reader, the sequence has apparently been reduced by half.

When combining steps in this way, though, there's a price to pay. Each step you've combined is arguably overloaded, containing more than one discrete task. That's not necessarily bad, but don't over-do it. Obviously any sequence could be condensed down to just one big step, but that's not useful.

When you condense steps, it's important to emphasize the vital sub-steps. For instance, this sequence has the same result as before, but notice that the most vital step (removing the baby from the basin before throwing out the bathwater) is "buried" as an afterthought in step 2:

1. Fill the basin with water and place baby in the basin
2. Wash the baby, and then remove
3. Throw out bathwater

Should a careless person read through this version of the algorithm and overlook the second clause of step 2, the baby is likely to get thrown out with the bathwater.

Step by step

Writing instructions accurately is only part of technical documentation. Making those instructions easy to process is just as important.