We learn what to do from the people who had trouble doing it.  To Abraham Lincoln, who suffered from depression, the remark is attributed that “Most people are about as happy as they make up their minds to be.”  It was the Talmudic grouch Shammai who said “Receive all men with good cheer.”  And it was Marcus Fabius Quintilianus, a writer wrestling with the ambiguities of Latin, who wrote “Take care not merely to make understanding possible, but to make misunderstanding utterly impossible.”

In case you’d like to post Quintilian’s original on your office wall, it’s “Quare non ut intellegere possit sed ne omnino possit non intellegere curandum.” 

Notice the Latin word for understanding there:  it’s intellegere, like our adjective “intelligent.”  But I think that in our modern world, we all know people of high intelligence who can’t be counted on to understand anything.

You may even know technical writers who say, “I don’t need to understand the material.  I can turn raw input into polished output by merely applying my own intelligence.”  But there’s a reason technical writers are supposed to understand the material.  It’s the same reason that pharmacists are supposed to understand the prescriptions.

Of course pharmacists should be unambiguous too.  I know that by the time I get home from the drug store, wipe my watery eyes, and read “2 × 3” on the package of sinus medicine, there’s a good chance I won’t remember whether the pharmacist said two pills three times a day or three pills twice a day.

Often technical writers slip into ambiguity because they fear wordiness.  A lot of technical writers like to shorten the phrase “in order to,” leaving only the “to.”  The remaining sentence doesn’t always ring clear.  For example, the TiePlumb home edition requires a CD writer in order to back up your necktie collection.  If you say that it requires a CD writer to back up your necktie collection, you sound as if it somehow compels the CD writer to do so.

I engaged an editor once who would leave a plain “to” behind where I wrote “If you want to” or “If you wish to.”  I’d write “If you want to pivot the picture, use the arrow keys,” and in the next draft I’d see “Use the arrow keys to pivot the picture.”

The major problem there is that the reader loses the distinction between a compulsory step and a discretionary step.  Double-click the thumbnail to open the picture.  Use the arrow keys to pivot the picture.  Click the T icon to give the picture a name.  What can I skip, and what must I perform?

A second contributing problem was that according to this editor’s techwriting teacher the action, being the most important thing the reader is looking for, should always begin the sentence.  So I would find instructions edited into a sequence like “Press S to bring the necktie to the screen.  Press plus or minus to make the picture lighter or darker.  Press Y to select the necktie.  Press D to delete the necktie from the database.”  As a reader on a sinus-medicine day, you could find your left hand pressing a destructive key before your brain had absorbed the whole sentence, which — to give you a fair chance — should have been “If you want to delete the necktie from the database, press D.”

The whole point of the instructions, after all, is to lead the reader from purpose to action.  To work the opposite way — action by action, learning the purpose as you go — is what comes naturally when you don’t have a manual.  Those who do read the manual deserve a structure that puts their needs at the fore while leaving the side issues easily sidelined.