Writing Procedures Part 2: The Basics

In the previous part of the article, I discussed the style aspect of the procedure. Now, I would like to provide some information on writing the procedure itself.

Starting sentence

The starting sentence briefly describes the task, which is performed by going through the procedure.

First and foremost, the technical writer needs to understand why and howе the user performs the task. The answer to that may form a short section that provides some context, like a brief introduction for the user. Remember to keep it short and helpful: each word should be useful and informative.

The starting sentence may be a part of the procedure if it has only one step.

Example:

To open the file,  // The starting sentence states the task.

Double-click the icon. // The only step of the procedure.

Use short instructions only if the task is performed in one step and the path to performing it is obvious to the user.

The procedure, which consists of several steps, also starts with a short sentence that should clearly state the task.

Example:

//You can add some description of the task here. “The completed tasks may overwhelm the Task list and // disperse your attention. You can archive the completed tasks to keep the Task list informative. You can view the archived tasks in the Archived section.”

To archive the task:

1. Go to the Tasks tab.
2. Right-click the task name to open the context menu.
3. Select Archive.
4. Press OK to approve the action. If the task is archived successfully, then its status will change to Archived. If the error has occurred, you will see the message on the screen.

There are constant discussions about the amount of similarity in the starting sentence (should the words like To <do the task> do the following steps/follow these steps). In my opinion, they are mostly scanned through and are not that important for the reader, but they heavily impact the voice. So, if you are confused about the form of the starting sentence, try various options and see which option is better for conducting the voice. And make sure that all procedures start in the same way throughout the document.

It is important to add the style of the starting sentence to the company style guide, so all the starting sentences in your guide will look similar to each other in all documents of your company. This way, the documents are much easier to scan, search, or translate.

Steps of the procedure

I recommend keeping sentences in the steps as short as possible. Each step should contain one action. However, use some empathy and attention – sometimes it is helpful to add some text or describe the options in a more detailed way, especially if the procedure describes the irreversible or hard-to-reverse process.

Example:

To archive the task:

1. Go to the Tasks tab.
2. To open the context menu, right-click the task.
3. Select Archive. Archiving the task makes it read-only. You can view the archived tasks in the Archive section.
4. To approve the action, press OK. If the task is archived successfully, then its status will change to Archived. If the error has occurred, you will see the message on the screen.

If the action is really simple and obvious, you can merge such actions in one step.

Example:

Go to Actions->Tasks -> Archived

Instead of describing each step separately.

If there is some uncertainty, then it might be better to separate the actions and provide some details for each step.

For optional steps, it may be helpful to provide a note or write the step in a way that makes it optional.

Example:

1. (optional) Mark the task as important to move it to the top of the list.
2. You may mark the task as important to move it to the top of the list.

If the step has two different ways, clearly state that the user has to choose one of them.

Example:

You can make a call in one of the following ways:

• Press Call.
• Double-click the user photo.

If the choice affects the outcome of the procedure, it might be better to consider writing a separate procedure for each outcome. Complex multi-way procedures are rarely easy to understand and comfortable to use.

The word order is also important to make a procedure scannable (and translatable). The preferred word order depends on the language, and it is better to specify the word order in the company Style guide. This way, all documents in the company will be similar to those of the user. It may be helpful to try different options and find the shortest and clearest one.

Step descriptions and warnings make the step more detailed and attract attention. They should not be separated from the step, but you may want to start them with a new line. Make this consistent by adding the rules to a style guide.

Note that the procedure should be as short as possible and best fit on one screen, so try to limit the number of steps to a reasonable number. If some process is too complicated, it might be a chance to improve the UI or the feature itself!

Clearly stating the result

Why would you read the procedure? To get the result. This means that the result should be obvious. Sometimes, the interface doesn’t clearly state that the user completed the task. Sometimes, the result can vary. The procedure should be completed with the sentence describing the clear positive result – how does the user know that the task was completed:

• Successfully – the goal stated in the starting sentence is achieved.

• Unsuccessfully – in this case, the best option is to provide detailed information in the error message via UI. Otherwise, write a short description what is the cause and how to fix it.

  
  

In this article, I shared some ideas on how to write the starting sentence, the steps, and the result. Welcome to the third part for more details on enriching the steps with media.