Editor's Corner

Have you ever been following a set of instructions and encountered a final step like, “Click OK to save your changes, or click Cancel”?

In years of reading software documentation (as a user, not an editor), I must have seen the phrase, “or click Cancel” hundreds of times, but I don’t remember ever choosing that option.

Technical documentation should be written to help users accomplish their goals. If you’re writing a document titled Setting Up a Printer, you can be certain that the reader’s goal is setting up a printer, not getting 99 percent of the way through setting up a printer and then abandoning the task.

This quirk seems limited to technical documentation. The navigation app on my phone doesn’t tell me, “Your destination is on the right. If you changed your mind and want to go home, make a U-turn in 200 feet.”

Similarly, I’ve never read self-undermining instructions in any of the following contexts:

• “Remove the engine oil cap and pour in six quarts of clean oil, or just pour the dirty oil back in.”
• “Hang the birdhouse from a tree, or rip out all the nails and throw the disassembled wooden pieces on the ground.”
• “Enjoy your sandwich, or scrape the mayonnaise back into the jar and put the bread slices in the cupboard.”

It is occasionally helpful to tell the reader how to abandon a particularly long task and complete it later. For example, you might write, “Click OK to submit the form. If you are not yet ready to submit the form, click Cancel. You can resume working on it the next time you log on.” But these situations are rare.

If you find yourself writing, “or click Cancel,” ask yourself whether that is something users might reasonably do. If not, leave that part out of the instructions.

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.