Si vous n'êtes pas à l'aise avec l'anglais, utilisez ceci :
Cet outil vous fournit une traduction automatisée en français.
Great Technical Writing Tell Your Users What To Expect
OVERVIEW
In your User Documentation, you direct your Reader to perform tasks with your product. If you don't tell your Reader what to expect when performing those tasks, you will have a baffled Reader, resulting in dissatisfaction and expensive calls to technical support.
EXAMPLE: REVERSE OSMOSIS WATER FILTER
I bought and installed a Reverse Osmosis water filter. The instructions told me to fill, and then empty (the instructions foolishly used the term "dump," which would have caused the destruction of the system) the tank.
The filter had a capacity of about 100 gallons per day. Thus I expected the initial fill (4.5 gallon tank) to take less than one hour. After about an hour the tank was still filling. Worried, I called the technical support. I was told that it takes about two hours for the tank to fill.
One line in the User Documentation would have eliminated that call: "The tank initially takes 2 hours to fill." Not knowing what to expect I, and perhaps other Users, wasted the time and money to call the technical support line.
EXAMPLE: UPGRADING A ROUTER'S SOFTWARE
I had some problems with my Cable/DSL (Internet-Ethernet) router. The internal control panel made it easy to check for and download updates to the internal software. The system told me that it would take a few minutes to check for updates (good), but it did not tell me how long the update would take to perform once I downloaded the file.
Not telling the User what to expect in terms of time is a mistake. I started the update and after a few minutes of operation (was it working?) I canceled the process. I re-started it again, and decided to wait longer to see what happened. It took a few minutes longer, and successfully completed.
It would only take a simple phrase such as "the software update can take up to five minutes to complete" to reduce the User's anxiety.
PROGRESS INDICATORS (as displayed in a windowing environment) are often useless. Some go beyond 100%, others are logarithmic: they move quickly in the early processing and wait, seemingly at the end, for a long time while processing is completing. Consider making progress indicators relate to the time of operation, not number of files.
Some progress/activity indicators have nothing to do with the program they are associated with. I have used virus checkers that have abnormally terminated, yet the activity indicator kept on moving. Make sure that progress/activity indicators do reflect activity of the associated program.
FILE DOWNLOADS DO IT
Telling the User what to expect is not a new concept. If you have ever downloaded files, the download site will often tell how long the file will take to download, based upon your Internet connection.
EXAMPLE: YOUR PRODUCT'S INDICATORS
While most examples of "telling the User what to expect" deals with the time needed to complete an activity, others can be related to the indicators and performance of the product.
I have a small smart battery charger that has a red light for each of the battery positions. Unfortunately, the operation of these lights is impossible to understand, and there is no description of how they work.
Here's what happens. When you first insert the battery, the light illuminates. A short while later (the charging still has many hours to go), the light goes off. Sometime toward the end of the charging cycle the light may go on again.
This is clearly confusing to the User. The User's expectation is that when the light goes out, the charging is completed. This would result in a lot of User frustration, as Users would try to use "charged" batteries that were not charged. The developers of the battery charger should explain the operation of these displays.
THE BOTTOM LINE
Tell the Users what to expect as they use your product. Often this information is the amount of time it will take for an operation to complete. For other products, you may have to tell the User what the indicators mean.
Don't leave your document Readers confused or left to figure things out on their own. Doing so will reduce your Users' comfort with your product, and increase your technical support costs.
BONUS : Great Technical Writing: The Two-edged Sword Of Reader Experience
Overview
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 books 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 dont, 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"...by 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
Assumptions
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.
Overview
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 books 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 dont, 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"...by 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
Assumptions
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.
