Great Technical Writing: The Two-edged Sword Of Reader Experience

Overviewinto the wet hair, leave in the hair for two or
When we write User Documents we rely on ourthree minutes, then rinse it out.
Reader's/User's experience to simplify our work.The problem arises with the combined product.
This can cause problems for the Reader. ThisShould the User leave the product in the hair for
article will discuss the effects of Readertwo or three minutes (as done with the
experience and how to minimize the negativeconditioner), or rinse it immediately (as done with
effects of incompatible experience, and how tothe shampoo)?
handle the writer's assumptions about the Reader.The User Document (product label) for a
Writer's Benefits: Relying on Reader Experiencecombined shampoo-conditioner should tell the User
When we write, we rely on our Reader'show to use the two-in-one product. Most such
experience to give us a "starting point" for ourlabels do not.
User Document. Often we make hiddenExample: Words Used in Unexpected Ways
assumptions about our Reader's experience.Your writing can set the expectations of the
Here are some examples where relying on ourReader, resulting in confusion when words are
Reader's experience makes things easy (andused unexpectedly.
causes problems) for us as writers:An article in the Technology Section (of a
Example: Using a Computer's Mousenewspaper on June 10, 2004, page B14)
In writing User Documentation for Graphical Userdescribed, "How the little guy can back up
Interface-based computer products (such as thecomputer data". The article was about computers.
Windows or Mac User interface), we assume thatWhen I came to the sentence: "Let's face it:
the the Reader knows how to use a mouse tobackups are boring and a hassle to boot." I
click on items, drag, etc. This saves muchwondered about the phrase "to boot."
background writing.In computer jargon, "boot" is the process where
Example: Cooking: How to Measure Ingredients;the computer starts up ("lifts itself by its
Termsbootstraps"...by a program originally called a
Cook books save space by (usually correctly)"bootstrap loader"). Does the author's quote about
assuming that a Reader can perform basic"hassle to boot" mean that if I do backups, then
cooking operations (such as measuringmy computer will be slower ("boring") and require
ingredients), and terms (such as puree or slice).more work from me to start up ("hassle to
Example: Common Acronymsboot")?
We rely on "common" acronyms such as AM andThe use of the phrase "to boot" is inappropriate in
PM to simplify our writing lives. However, manythis article, given that "to boot" has multiple
Readers use a 24 hour clock, and thus AM andmeanings. The author used it as slang for "in
PM are meaningless to them.addition to." Since the article was about
Beware of any acronyms that you assume thatcomputers, I thought of the computer meaning of
your Reader knows. It is best to define acronyms"to boot." The sentence would be less confusing if
in line (perhaps in parentheses) when they arethe author left out "to boot," as: "Let's face it:
first presented in that part of the User Document.backups are boring and a hassle." We'll return to
You cannot define them only the first time theythis example shortly.
appear in the User Document. This assumes --Example: Functional Fixedness
incorrectly -- that Users read your UserAn object's function is fixed in a person's mind.
Document from start to finish.For example, a hammer's function is to pound
Problems Writers Cause When Assuming Userthings. Experiments have demonstrated that
Experiencepeople have a hard time using a hammer for an
Our assumptions as writers can get us intounusual function, such as a paperweight, a prop,
trouble.or a lever. This is called functional fixedness.
Example: Unfamiliar WordsFunctional fixedness can limit the usefulness of
Here's a gardening example: Acme's (a fictitiousyour product. Your User Document should
company) Illustrated Guide to Gardening in Canadaattempt to overcome functional fixedness.
(1979) makes an incorrect assumption about itsPerhaps this example will show how critical I am
Readers:of User Documents.
In one of their definitions they use a term, "theI have a wrist global positioning satellite (GPS)
axil of a leaf" to define another term. "Axil of adevice that keeps track of my long walks.
leaf" is not listed in the book's index, and there isSweaters and heavy coats, needed for walking in
no glossary in the book. Clearly this bookthe winter, make it difficult to wear the GPS
assumes that the Reader understands the termdevice on the wrist. But it is a WRIST device.
"the axil of a leaf." I don't, and am thereforeFunctional fixedness arises, causing me struggle to
unhappy with the presentation.use the GPS on my wrist. But it turns out that
Solution: Provide a glossary of gardening terms orthe GPS works well when used in a pocket.
a reference to a page in the book where theThe GPS User Document should mention this
term is defined.(obvious?) capability, thus reducing the functional
Example: Assuming Students' Experiencefixedness associated with the WRIST GPS. In my
Here is an example where an (unstated)defense: I am not sure that putting the wrist GPS
assumption by a training company rendered onein a pocket is more obvious than using a hammer
of their courses useless.as a paperweight.
In order to do the exercises in a computerExample: Humor
programming course, students had to be able toHumor relies on:
use an editor (a simple word processor) to. a subtle knowledge of the language (for example
program the system. The only editor available ona pun)
the course machines was a UNIX editor known as. or a knowledge of an event (perhaps a current
vi.event or entertainment event)on which the
Unfortunately, the students were not told thathumor is based. Here's an example, from an old
they needed to use the vi editor. The coursejoke:
presenters assumed that the students knew vi."You're so funny, you should be on a stage.
The students did not, and they spent half theThere's one leaving in 15 minutes."
course time trying to learn and deal with vi.This joke relies on the Reader's knowing the two
The hidden assumption by the training companymeanings of "stage": (1) a place for performing,
resulted in a failed learning experience (theand (2) transportation used in the western United
students never needed to use vi again). It wastedStates in the 1800's. Most Readers might not
two days of the four-day course time.know the second meaning, rendering the humor a
Don't Present Assumptions in a Sneaky Wayconfusing waste of words.
If the training company had said that, "We trainEarlier we examined the sentence: "Let's face it:
on UNIX systems," then they leave a way outbackups are boring and a hassle to boot." The
for themselves when they disappoint studentsauthor used the phrase "to boot" as some form
who do not know the vi editor. When confronted,of folksy talk or humor. It confused the Reader.
the company could respond with, "We told you itEliminate Humor from Your User Document
was a UNIX system. You should know that vi is. Humor will only confuse Users who do not
the editor available on that system."understand it.
This sneaky statement of the assumption is. Humor is difficult, if not impossible, to translate
foolish. It will result in a lose-lose situation.into other languages.
The Bottom LineI suggest that you use a writing style that is
As writers, we to make assumptions about ourinformal and conversational, but with no attempts
Reader's experience. However, if you makeat humor. Remove attempts at humor when you
assumptions, then make sure that you tell thereview and revise your writing.
Reader what you assume about him/her.If you want to write humor, do it elsewhere (you
Think about the assumptions that you makeshould be on a stage). User Documents are no
about your Reader. Are these assumptions validplace to practice your humor.
(that is, can you really expect your Readers toThe Bottom Line
meet your assumptions)? If there is any doubt inAssumptions
your mind, include information explaining the termsBe careful about what you assume about your
and procedures that you assume.Reader. When in doubt whether or not a Reader
Make sure that when you state assumptions, thatknows something:
you present them in a way that the Reader. State your assumptions about your Reader
(student) can understand what the assumptionState the assumptions in a way that the Reader
means to them. Don't be sneaky about presentingcan relate to
the assumptions.. When in doubt, add the information that you
User Experience Can Cause Trouble for Writersassume, or
Your Reader's experience can cause confusion.. Tell your Reader where to find the assumed
Here are some examples:information
Example: Shampoo/Conditioner ProductBy providing or pointing to this assumed
One of my favorite examples is a combined hairinformation, you increase your audience
shampoo and conditioner product. If a User hasReaders' Experience
experience with the separate products, then theirBe aware of how your Reader's experience
experience is to:influences how he/she interprets your User
* Shampoo: Wet thenhair. Massage shampoo intoDocument or uses your product. If necessary add
the hair, then rinse it out.material to your User Document to counter your
* Conditioner: Wash the hair. Massage conditionerReader's incompatible experience.