Great Technical Writing The Two Edged Sword Of Reader Experience

Great Technical Writing The Two Edged Sword Of Reader Experience


When we​ write User Documents we​ rely on​ our Reader's/User's experience to​ simplify our work. This can cause problems for the​ Reader. This article will discuss the​ effects of​ Reader experience and how to​ minimize the​ negative effects of​ incompatible experience,​ and how to​ handle the​ writer's assumptions about the​ Reader.

Writer's Benefits: Relying on​ Reader Experience

When we​ write,​ we​ rely on​ our Reader's experience to​ give us a​ "starting point" for our User Document. Often we​ make hidden assumptions about our Reader's experience.

Here are some examples where relying on​ our Reader's experience makes things easy (and causes problems) for us as​ writers:

Example: Using a​ Computer's Mouse

In writing User Documentation for Graphical User Interface-based computer products (such as​ the​ Windows or​ Mac User interface),​ we​ assume that the​ the Reader knows how to​ use a​ mouse to​ click on​ items,​ drag,​ etc. This saves much background writing.

Example: Cooking: How to​ Measure Ingredients; Terms

Cook books save space by (usually correctly) assuming that a​ Reader can perform basic cooking operations (such as​ measuring ingredients),​ and terms (such as​ puree or​ slice).

Example: Common Acronyms

We rely on​ "common" acronyms such as​ AM and PM to​ simplify our writing lives. However,​ many Readers use a​ 24 hour clock,​ and thus AM and PM are meaningless to​ them.

Beware of​ any acronyms that you assume that your Reader knows. it​ is​ best to​ define acronyms in​ line (perhaps in​ parentheses) when they are first presented in​ that part of​ the​ User Document.

You cannot define them only the​ first time they appear in​ the​ User Document. This assumes -- incorrectly -- that Users read your User Document from start to​ finish.

Problems Writers Cause When Assuming User Experience

Our assumptions as​ writers can get us into trouble.

Example: Unfamiliar Words

Here's a​ gardening example: Acme's (a fictitious company) Illustrated Guide to​ Gardening in​ Canada (1979) makes an​ incorrect assumption about its Readers:

In one of​ their definitions they use a​ term,​ "the axil of​ a​ leaf" to​ define another term. "Axil of​ a​ leaf" is​ not listed in​ the​ book’s index,​ and there is​ no glossary in​ the​ book. Clearly this book assumes that the​ Reader understands the​ term "the axil of​ a​ leaf." I don’t,​ and am therefore unhappy with the​ presentation.

Solution: Provide a​ glossary of​ gardening terms or​ a​ reference to​ a​ page in​ the​ book where the​ term is​ defined.

Example: Assuming Students' Experience

Here is​ an​ example where an​ (unstated) assumption by a​ training company rendered one of​ their courses useless.

In order to​ do the​ exercises in​ a​ computer programming course,​ students had to​ be able to​ use an​ editor (a simple word processor) to​ program the​ system. the​ only editor available on​ the​ course machines was a​ UNIX editor known as​ vi.

Unfortunately,​ the​ students were not told that they needed to​ use the​ vi editor. the​ course presenters assumed that the​ students knew vi. the​ students did not,​ and they spent half the​ course time trying to​ learn and deal with vi.

The hidden assumption by the​ training company resulted in​ a​ failed learning experience (the students never needed to​ use vi again). it​ wasted two days of​ the​ four-day course time.

Don't Present Assumptions in​ a​ Sneaky Way

If the​ training company had said that,​ "We train on​ UNIX systems,​" then they leave a​ way out for themselves when they disappoint students who do not know the​ vi editor. When confronted,​ the​ company could respond with,​ "We told you it​ was a​ UNIX system. You should know that vi is​ the​ editor available on​ that system."

This sneaky statement of​ the​ assumption is​ foolish. it​ will result in​ a​ lose-lose situation.

The Bottom Line

As writers,​ we​ to​ make assumptions about our Reader's experience. However,​ if​ you make assumptions,​ then make sure that you tell the​ Reader what you assume about him/her.

Think about the​ assumptions that you make about your Reader. Are these assumptions valid (that is,​ can you really expect your Readers to​ meet your assumptions)? if​ there is​ any doubt in​ your mind,​ include information explaining the​ terms and procedures that you assume.

Make sure that when you state assumptions,​ that you present them in​ a​ way that the​ Reader (student) can understand what the​ assumption means to​ them. Don't be sneaky about presenting the​ assumptions.

User Experience Can Cause Trouble for Writers

Your Reader's experience can cause confusion. Here are some examples:

Example: Shampoo/Conditioner Product

One of​ my favorite examples is​ a​ combined hair shampoo and conditioner product. if​ a​ User has experience with the​ separate products,​ then their experience is​ to:

* Shampoo: Wet thenhair. Massage shampoo into the​ hair,​ then rinse it​ out.
* Conditioner: Wash the​ hair. Massage conditioner into the​ wet hair,​ leave in​ the​ hair for two or​ three minutes,​ then rinse it​ out.

The problem arises with the​ combined product. Should the​ User leave the​ product in​ the​ hair for two or​ three minutes (as done with the​ conditioner),​ or​ rinse it​ immediately (as done with the​ shampoo)?

The User Document (product label) for a​ combined shampoo-conditioner should tell the​ User how to​ use the​ two-in-one product. Most such labels do not.

Example: Words Used in​ Unexpected Ways

Your writing can set the​ expectations of​ the​ Reader,​ resulting in​ confusion when words are used unexpectedly.

An article in​ the​ Technology Section (of a​ newspaper on​ June 10,​ 2004,​ page B14) described,​ "How the​ little guy can back up computer data". the​ article was about computers. When I came to​ the​ sentence: "Let's face it: backups are boring and a​ hassle to​ boot." I wondered about the​ phrase "to boot."

In computer jargon,​ "boot" is​ the​ process where the​ computer starts up ("lifts itself by its bootstraps" a​ program originally called a​ "bootstrap loader"). Does the​ author's quote about "hassle to​ boot" mean that if​ I do backups,​ then my computer will be slower ("boring") and require more work from me to​ start up ("hassle to​ boot")?

The use of​ the​ phrase "to boot" is​ inappropriate in​ this article,​ given that "to boot" has multiple meanings. the​ author used it​ as​ slang for "in addition to." Since the​ article was about computers,​ I thought of​ the​ computer meaning of​ "to boot." the​ sentence would be less confusing if​ the​ author left out "to boot,​" as: "Let's face it: backups are boring and a​ hassle." We'll return to​ this example shortly.

Example: Functional Fixedness

An object's function is​ fixed in​ a​ person's mind. For example,​ a​ hammer's function is​ to​ pound things. Experiments have demonstrated that people have a​ hard time using a​ hammer for an​ unusual function,​ such as​ a​ paperweight,​ a​ prop,​ or​ a​ lever. This is​ called functional fixedness.

Functional fixedness can limit the​ usefulness of​ your product. Your User Document should attempt to​ overcome functional fixedness. Perhaps this example will show how critical I am of​ User Documents.

I have a​ wrist global positioning satellite (GPS) device that keeps track of​ my long walks. Sweaters and heavy coats,​ needed for walking in​ the​ winter,​ make it​ difficult to​ wear the​ GPS device on​ the​ wrist. But it​ is​ a​ WRIST device. Functional fixedness arises,​ causing me struggle to​ use the​ GPS on​ my wrist. But it​ turns out that the​ GPS works well when used in​ a​ pocket.

The GPS User Document should mention this (obvious?) capability,​ thus reducing the​ functional fixedness associated with the​ WRIST GPS. in​ my defense: I am not sure that putting the​ wrist GPS in​ a​ pocket is​ more obvious than using a​ hammer as​ a​ paperweight.

Example: Humor

Humor relies on:

. a​ subtle knowledge of​ the​ language (for example a​ pun)
. or​ a​ knowledge of​ an​ event (perhaps a​ current event or​ entertainment event)

on which the​ humor is​ based. Here's an​ example,​ from an​ old joke:

"You're so funny,​ you should be on​ a​ stage. There's one leaving in​ 15 minutes."

This joke relies on​ the​ Reader's knowing the​ two meanings of​ "stage": (1) a​ place for performing,​ and (2) transportation used in​ the​ western United States in​ the​ 1800's. Most Readers might not know the​ second meaning,​ rendering the​ humor a​ confusing waste of​ words.

Earlier we​ examined the​ sentence: "Let's face it: backups are boring and a​ hassle to​ boot." the​ author used the​ phrase "to boot" as​ some form of​ folksy talk or​ humor. it​ confused the​ Reader.

Eliminate Humor from Your User Document

. Humor will only confuse Users who do not understand it.
. Humor is​ difficult,​ if​ not impossible,​ to​ translate into other languages.

I suggest that you use a​ writing style that is​ informal and conversational,​ but with no attempts at​ humor. Remove attempts at​ humor when you review and revise your writing.

If you want to​ write humor,​ do it​ elsewhere (you should be on​ a​ stage). User Documents are no place to​ practice your humor.

The Bottom Line


Be careful about what you assume about your Reader. When in​ doubt whether or​ not a​ Reader knows something:

. State your assumptions about your Reader
State the​ assumptions in​ a​ way that the​ Reader can relate to
. When in​ doubt,​ add the​ information that you assume,​ or
. Tell your Reader where to​ find the​ assumed information
By providing or​ pointing to​ this assumed information,​ you increase your audience

Readers' Experience

Be aware of​ how your Reader's experience influences how he/she interprets your User Document or​ uses your product. if​ necessary add material to​ your User Document to​ counter your Reader's incompatible experience.

Great Technical Writing The Two Edged Sword Of Reader Experience

Related Posts:

No comments: Comments Links DoFollow

Powered by Blogger.