Writing Procedures Part 1: Voice and Style

First of all, let’s see what a procedure is. A procedure is a piece of text that provides step-by-step recommendations on how to perform a task. The main purpose of a procedure is to tell the user how to achieve a certain result. Therefore, a procedure should have:

\

1. Clearly stated task.

2. Clearly stated result (or several results).

3. Clear and achievable steps.

4. Consistent style.

   \

The procedures may form the biggest part of your document. I will describe the task of writing a procedure.

Let’s review only the text procedures in this article. In many cases, a creative technical writer will be more than happy to use a single screenshot or a short video to show the user how to do something. Using media will be discussed later.

Since the procedure is a set of steps that command the user to do something, it should be written in a friendly and supportive voice. However, be mindful of choosing the tone of the voice: sometimes, if you need to bring the user’s attention to important information, you should change the tone to more assertive and strong. For example, this can be used when giving notes or warnings.

Note: Use the strong voice only to warn the user or describe the consequences. It should stay noticeable to attract user’s attention to important information.

Example:

• Procedure: To edit the task, press Edit. You will see the edit window on the screen.
• Warning: You will be unable to reverse the archiving. The task will remain read-only.

As the procedure is a very specialized piece of text, it is worth putting an effort into defining a specific style for it.

Keep in mind the following point: users can and will scan the procedure to find that specific step that is not so easy to perform. This means that all procedures in the document should be easy to scan – this equals being written in the same style.

Make sure that the style is described in the style guide, and use that style when you write the procedures.

In the second part of the article, I will talk about how to write the procedure itself: how to start and how to lead the user through its steps.