Najjar, L. J. (1991, November). Eschew obfuscation (TM 52.0002). Atlanta, GA: IBM Corporation.

Eschew Obfuscation

Document Number TM 52.0002
Lawrence J. Najjar
IBM Corporation
P.O. Box 2150
WG02C
Atlanta, GA 30301-2150
Tie line 336-7071

ESCHEW OBFUSCATION

These words were posted over my high school English teacher's classroom door.  I passed that sign every day for four years, but I never bothered to find out what it meant.   Several years after high school, with time and a dictionary on my hands, I decided to look up the strange words.  I discovered that "eschew obfuscation" means "avoid confusion."

I recall those words when reading or writing documentation for computer users.  Clear, easy-to-understand user documentation is an important part of a well-designed human-computer interface.  Computer users refer to the documentation to decide whether to purchase the product, to learn how to use the product, and to solve problems encountered while using the product.

In the spirit of "eschewing obfuscation," here are some brief suggestions to keep in mind when you write user documentation.

• Write simply -- Write for the worst case reader in your intended audience.  This reader has the lowest reading comprehension level, least amount of experience, and lowest motivation to read your text.  You can make it easier for this reader to understand your text by using simple words, directions, and explanations.  Where possible, replace text with graphics.



• Write concisely (Strunk & White, 1979; Williams, 1985) -- Your readers will likely be in a hurry, under stress, or both.  Make it easy for them to find what they need by using short chapters, paragraphs, sentences, and words.  Brevity is often clarity.



• Assume the reader is naive -- Write for a person who is more naive than the intended product user.  By not assuming reader knowledge, you increase the number of people who can buy and use your product.  If a short explanation makes it easier for a naive person to understand your text, include the explanation.



• Use the active voice (Strunk & White, 1979) -- The active voice is clearer than the passive voice.  Here is a sentence written in the active voice:  To start, you insert the disk into drive B.  Here is the same sentence written in the passive voice:  To start, the disk is inserted into drive B.  The active voice has the advantage of telling the reader who does what.



• Use the present tense (Strunk & White, 1979) -- The present tense is short and direct.  Compare these two sentences.  The first sentence is written in the present tense:  The computer processes the data.  The second sentence is written in the progressive, passive, future perfect:  The computer will have been processing the data.  Also, try to write in one tense.  If you need to use two simple verb tenses, consider using the present and past tenses.



• Use positive statements (Strunk & White, 1979; Williams, 1985) -- Tell the reader what to do.  Don't tell the reader what not to do.  People respond faster to positive instructions ("Right turn only") than to negative instructions ("No left turn") (Whitaker & Stacey, 1981).



• Use common language rather than jargon -- Just because you know computers, don't assume that the reader does.  If you can get your ideas across without using "computerese," you are less likely to confuse and frustrate your reader.



• Avoid acronyms -- Although acronyms save space, they assume your reader is familiar with your definition.  Even if you define your acronym initially, the reader may skip around in your text and miss the definition.  Use whole words to make sure the reader knows what you mean.



• Lead the reader logically and sequentially through related information -- Try to put in one section all the information the reader needs on a topic.  If you force the reader to flip pages to find related information, you will increase the chances of confusing and frustrating your reader.

My English teacher's advice was good.  Don't "eschew obfuscation" when you can "avoid confusion."

References

Strunk, W., Jr. and White, E. B. (1979). The elements of style. New York, Macmillan.

Whitaker, L. A., and Stacey, S. (1981). Response times to left and right directional signs. Human Factors, 23, 447-452.

Williams, J. M. (1985). Style: Ten lessons in clarity and grace. Glenview, IL: Scott, Foresman and Company.

Biography

Larry Najjar is a human factors engineer in IBM's Industrial Sector Division Software Usability department in Atlanta, Georgia.  He earned a MS in Engineering Psychology from the Georgia Institute of Technology and has authored 14 publications.