Posted by: episystechpubs | March 5, 2018

Editor’s Corner: Writing Clear Steps

Writing clear instructions is a useful skill for everyone. Even if you are not a technical writer, you may need to document a procedure before handing off a job responsibility, or a client or coworker may ask you how to perform a task.

Instructions are mostly lists of numbered steps. If you can write clear steps, you are well on your way to writing clear instructions.

Rule #1: Avoid “Should”

Original step: The AutoRecover field should be set to Yes.

The problem with the word should is that it’s ambiguous. As written, this step could reasonably mean any of the following things:

  • The AutoRecover field is probably already set to Yes.
  • It would be nice if the AutoRecover field were set to Yes, but it’s not required.
  • The AutoRecover field needs to be set to Yes.

Rule #2: Use the Active Voice

First revision: The AutoRecover field needs to be set to Yes.

This is an improvement. At least we know that this step is mandatory. But there’s still the question of who needs to perform this action.

Two messy roommates might agree that the dishes need to be washed or the living room needs to be vacuumed, but without reaching an agreement about who will do what, there probably won’t be any action.

It’s the same situation here. Using the passive voice causes confusion about whether the reader needs to perform the action or wait for someone else to do it.

Second revision: Set the AutoRecover field to Yes.

This is a well-written step with an imperative verb. It is clear what action the user needs to take.

Ben Ritter | Technical Editor | Symitar®
8985 Balboa Avenue | San Diego, CA 92123
619-682-3391 | or ext. 763391 | www.Symitar.com

Symitar Documentation Services

NOTICE: This electronic mail message and any files transmitted with it are intended
exclusively for the individual or entity to which it is addressed. The message,
together with any attachment, may contain confidential and/or privileged information.
Any unauthorized review, use, printing, saving, copying, disclosure or distribution
is strictly prohibited. If you have received this message in error, please
immediately advise the sender by reply email and delete all copies.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Categories

%d bloggers like this: