4.2 Writing steps

This section explains how to write your action-based steps, which is vital in tutorials.

How do you write the action you want the audience to do?

The purpose of software documentation, tutorials, and instructions is to explain how to do specific actions and tasks clearly and concisely, but you may notice that some tutorials, especially websites, include long paragraphs which explain action, and provide numbered steps in the headings only.  This does not help the audience.

Think about how you use tutorials.  Do you read them like books? Of course not. You do the action as you read, so think about the cognitive load it takes to read, do action, and then search for your place in the text before figuring out what you need to do next.

As a technical communicator, it is your job to do as much work as possible for your audience and breaking down the steps into the smallest components possible is necessary. Writing, organizing, and designing steps clearly allows the audience to complete the action easily, which allows you to fulfill the purpose of the document and allows them to do the job they need to do with the software.

As you write the steps for your tutorial, open the software and do the actions yourself. This way, you won’t skip or forget steps, and you can write exactly what you do in the clearest terms possible. Additionally, you can take screenshots and snips of your computer interface, edit the images, and upload them directly to your tutorial.

As you write steps for your tutorial, you must

1. 1. 1. Break down actions into discrete units
      2. Include a clear heading for each discrete unit
      3. Number the individual actions, also known as tasks, WITHIN each unit
      4. Write each action in the imperative
      5. Organize chronologically
      6. Use indentations to set steps apart from other text
      7. Include an image for each action next to or immediately below the written action
      8. Add double spaces between each written step and each image

Break down actions into discrete units

Discrete units of action are groups of actions that go together logically. As you are doing your prewriting and outlining, as discussed in Chapter 2 of this tutorial, consider what the audience needs to know how to do.  Breaking the actions down into discrete units helps you write more clearly, concisely, and accurately, but remember that this is a recursive writing process, so don’t be afraid to reorganize and play with these discrete units.

The purpose of this is to avoid writing unnecessary paragraphs which users find difficult to read as they do action.

When users read a tutorial, they are scanning for the information on how to do the action.  They are also DOING the action at the same time so they go back and forth between the technology and the tutorial.  Writing paragraphs will cause significant confusion for the audience.

Include a clear heading for each discrete unit

Once you have broken down your actions into discrete units, think about your different headings and the necessary levels. For example, in the Chapter 3, Table of Contents (ToC) section of this tutorial, there are two discrete units of action: one for creating a ToC in Word and one for creating a ToC in Google Docs. In that section, Chapter 3: PDF Organization and Content is a level one heading while Creating a Table of Contents is a level two heading. Why aren’t the steps all placed under the ToC level two heading?

1. 1. 1. Separating the instructions by technology is more logical.
      2. The audience needs to choose which technology they want to use before beginning.
      3. Adding third level headings of Creating a Table of Contents in Word and Creating a Table of Contents in Google Docs narrows the focus which requires you to start your numbering system over at 1 after the second, third level heading.

Would it make sense to number the level three headings? You could, but that does not eliminate the need for numbered ACTIONABLE and imperative steps within those sections. For example, could all headings in chapter 3 of this tutorial be numbered as follows?

1. 1. 1. 1. 1. 1. 3. PDF Organization and Content (level 1)

3.1 What is included in Front Matter (level 2)

3.1.1 Title Page (level 3)

3.1.2 Table of Contents (level 3)

3.1.2.1 ToC in Word (level 4)

3.1.2.2 ToC in Google Docs (level 4)

Yes. You could number your headings like this, as many professional, highly technical software documentation do, but does this negate the need for numbered actionable steps? Absolutely not.

Number the individual actions WITHIN each unit

Under each heading, start your numbering system over at 1 and number each individual action. Do not put multiple actions in one step number even if the steps seem extremely closely related.

As you write the actions, make sure you do them yourself with the software you have chosen. This way, you can slowly write, number, and do, so you don’t accidentally skip a step.

Write each action in the imperative

Since you write directly to the audience using the second person point of view (you), if you wrote out complete sentences for actions, you would start each step with “you should” or “you need to,” which would be redundant and would force your audience to search for the action, which is the verb.

To avoid the repetition and focus on the action, start with the verb instead. This is called the imperative or command voice. For example:

1. 1. 1. Click
      2. Search
      3. Scroll

Organize chronologically

You may be familiar with organizational chronology because of movies you have watched and stories you have read.  Chronology means that the order of action takes place in linear time: first, second, third.

Most narratives are organized this way, but so are tutorials, documentation, and instructions since one action must come before another action logically.  In other words, what should your audience do first? Download a software program or install a software program?  Clearly, they need to download it before they can install it.

Use indentations to set steps apart from other text

Chapter 6 explains alignment more fully, but you do not want your paragraphs, headings, and all steps to be left aligned to the one-inch margin.  Consistent left side justification is great for reports and letters, but for tutorials, variations in alignment help the audience to scan your content quickly.

Indenting steps provides more active space on the page and helps your user see the imperative verbs, so they can do the action efficiently.

Include an image for each action next to or immediately below the written action

As you have learned in Redish’s Letting Go of the Words, you should write and design documents concurrently since both need to work in harmony.  If you write first, then you will spend considerable extra time designing.

The same is true of writing actionable steps and creating images.  If you do both at the same time, you work more efficiently.  Since you are writing software documentation, and you are using a specific platform in your document, you should open the program, do the action, write, and take snips to include in your tutorial. Please see Images and Figures in chapter 5 of this tutorial.

Add double spaces between each written step and each image

Remember that active space allows the audience to easily scan the content, and since readers are doing the action as they read, double spacing the content allows them to move through the steps more quickly.  You don’t want to force the audience to search for information which could frustrated them.