 |
Great Technical Writing: Tell your Users What to Expect
Author: Barry Millman  | Posted: 18-09-2007 | Comments: 0 | Views: 28 | Rating: (51)  (?) 
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.
Rate this Article:
Current: 5 / 5 stars - 1 vote(s).
Article Source: http://www.articlesbase.com/non-fiction-articles/great-technical-writing-tell-your-users-what-to-expect-216515.html
About the Author:Barry Millman, Ph.D., has a Bachelor of Science in Electrical Engineering (1966, Carnegie Institute of Technology) and an M.Sc. and Ph.D. in Psychology (Human Information Processing, University of Calgary). He has been a consultant for over 25 years, an instructor, course developer, and award-winning speaker. For the past seven years he has been researching and creating resources to help organizations create great User Documents.
Visit: http://www.greatuserdocs.com/ for resources to help you create the User Documents that your Product needs and your Users deserve.
Visit http://www.greatuserdocs.com/ReadingRoom.htm for more articles like this one.
|
Submitting articles has become one of the most popular means of generating quality backlinks and targeted traffic to your website. Join us today - It's Free! |
|
Related Articles
Deciding What To Write-Can You Get There From Here?
By: Scott Lindsay | 26/08/2006 | Careers
When writing an article or story, how exactly do you decide what to write? Do your characters develop as you go when writing fiction? Does your plot unfold by chance? Do you have a clear idea of where your story or article is going before you actually beg
Write Better And Faster Using The Index Card Method
By: Brian Vogt | 17/12/2007 | Writing
In this article I'm going to discuss the "index card method" of writing. If you haven't ever tried it, you should know that using index cards to write is a very good and useful way to get the job done. It's easy once you get the basic idea, and if...
How To Avoid Clichés - That Sounds Familiar
By: Scott Lindsay | 26/08/2006 | Careers
When writing articles, stories for full blown manuscripts it is often in your best interest to avoid common phrases or colloquialisms. Many writers refer to the overuse of these phrases as cliché and they avoid them like the plague.
Before Painting Words
By: Scott Lindsay | 29/08/2006 | Careers
No matter what kind of writing you consider your forte you might want to consider the use of a ‘learning log'.
The process of writing generally requires research.
How To Write A Book
By: Brian Vogt | 06/01/2008 | Writing
Many people dream of writing their own book. The sad fact is that for every 500 people who want to write a book, there might be only 1 or 2 who actually do it. Somehow, we get it stuck in our minds that we "can never do that" and that...
One Epic Flashback
By: Scott Lindsay | 29/08/2006 | Careers
You've probably watched a movie where you observe the lead character in a quiet, contemplative moment.
New Technical Writer: Avoiding the Interview-writing Disconnect
By: Barry Millman | 16/04/2007 | Interviews
Lost or garbled information is a terrible waste. Especially if it's the information you gathered from an interview and must now write into your User Document. Here's how to prevent that waste.
Thinking In Blocks
By: Brian Vogt | 03/02/2008 | Writing
I have always been a very organized person-on the outside. On the inside is an entirely different story. I am, at best, "scattered". My mind, my thoughts, my emotions are constantly all over the place. By the time I have caught up with one thought, I have many more waiting...
Got a Question? Ask.
Ask the community a question about this article:
Frequently Asked Questions
What are the options for self-publishing, advantages and disadvantages?
By: Ecrivaine32 | 16-10-2007
What are the options for self-publishing and the advantages and disadvantages of these? I'm thinking of beginning my own publishing company, but I'm not sure what would be most beneficial or what I should take into account.Options I've considered are: Publish e-Books, and do so through Lulu or iUniverse, or a similar company; Publish through Lulu or some other site and sell the print version; Put my own name on a publishing company and either publish books Print On Demand or via some sort of e-Book software and sell them from my site or via Amazon, etc.I'll take any helpful ideas, because seeing all of the options from people more knowledgeable about publishing and marketing their books online will help me. Thanks!
Hi i am joseph writing from ghana wishing to have ...
By: agbeyjoseph | 12-10-2007
hi i am hi i am joseph writing from ghana wishing to have friends all over the world
Publishing companies in US
By: jake.brown | 07-10-2007
What are some of the more prestigious publishing companies in America?
Can't do e-pals, pen pals from a different country ...
By: Tanya S. | 07-10-2007
Can't do e-pals, pen pals from a different country?I would like to begin snail mail/ pen pals with a classroom from another country with correspondence in English or Spanish. Our class has no access to computers!
"The Story of an Hour"
By: royalpro | 26-09-2007
what Are the 10 events in the story "The story of an hour"?
Poters five force model in choclate industry? what ...
By: aladin_2008 | 07-09-2007
Poters five force model in choclate industry? Wat r the internl externl threats? Which r the substitute? Who r the buyers & sellers? Who would b the new entrants?
Q&A Powered by: 
Latest Non-Fiction Articles
Don't Let Good Grammar Spoil Good Writing
By: Philip Yaffe | 19/08/2008
Good grammar is fundamental to good writing, right? Wrong. However, years of experience working with people who use English as a second or third language have demonstrated that focusing too much on grammar can actually be detrimental to good writing. It's a question of priorities.
Modern Helicopters-the Eh-101 Merlin
By: K. Crockett | 16/08/2008
AgustaWestland is a joint venture formed by Agusta of Italy, makers of the A-109, and Westland of Great Britain, makers of the Lynx. The EH-101 is a direct competitor to the Sikorsky S-92 and was developed for both military and civil roles.
Animals
By: shivani suraiya | 15/08/2008
All about animals. About their origin, their lifestyles and their habitats including some interesting facts on different subjets. mostly based on mammals overing all extinct mammals around the world and which are not very well known.
The Three Speech Writing SECRETS You MUST Know - The Definitive Speech Writing How to Guide
By: Stuart Brown | 15/08/2008
In this article I am going to explore several techniques as to how you can improve your speech writing abilities, and also how to approach writing a speech for certain different circumstances. Whether it be for a wedding, where perhaps you are the best man, or for an important business meeting where you really need to impress. And tell you the three secret ingredients every speech needs.
Writing Your Thoughts – the Carrot and Stick Strategy
By: Nick Sanders | 14/08/2008
When you are writing, having a strategy in mind is rather useful – especially when you are wanting your reader to commit to something or someone. You will want to lead the reader in the direction you intend to finish upon and don’t want to cause confusion and misdirection in your writing. Here are a few tips on the carrot and stick strategy of writing that is good to use in a time of need.
Science: Guaranteed to Curb Creative Thinking!
By: Natasha | 13/08/2008
In today's sci- fi world dominated by facts and figures, the essence of life and belief in God's miracles have been thrust aside as illogical and futile, nonetheless God NEVER fails to surprise us....
How to Develop Your Book’s Structure
By: Melinda Copp | 12/08/2008
A man came to me last week because he needed help writing his book. He told me that he’s had this project on his to-do list for years, but he just couldn’t seem to get started. He’s literally been staring at the task—start writing my book—almost every day, and when he came to me, he still hadn’t done it.
How to Write a Bibliography
By: Stuart Brown | 11/08/2008
If you're like me, you probably put your heart and soul into creating a wonderful paper, essay or article. You know that you conducted the necessary research and that you wrote a sound paper. However, you are now at the end and you may be wondering, how can you write a bibliography? Well, I am here to tell you how.
More from Barry Millman
Great Technical Writing: the User-product Life Cycle - a Documentation Tool
By: Barry Millman | 29/10/2007 | Non-Fiction
The User-Product Life Cycle (U-PLC) is a powerful tool for the User Document writer. Use the U-PLC to generate the high-level topics for your User Document.
How Poor In-house User Documents Cost you Twice & What to Do About it
By: Barry Millman | 31/07/2007 | Writing
Many organizations produce in-house tools or modify commercially-available tools for their own use. These tools should get documented so they are of use to others in the organization.
If this documentation is not created or is poorly written, it costs you twice.
Great Technical Writing: User Document Headings Should be Guideposts, not Advertisements
By: Barry Millman | 28/06/2007 | Non-Fiction
Most heading are designed to entice us to read further. Headings in User Documents should enable your Reader to decide whether or not to continue reading that section. Use effective headings to make it easy for your Reader to access and understand your User Document.
Great Technical Writing: Improve your Readers' Access With a Visual Index
By: Barry Millman | 06/06/2007 | Non-Fiction
People are visual creatures. They look at your product, and see, for example, a button or display. They want to find out about that control or indicator. A Visual Index is a simple but powerful document access tool that enables your Readers to find the information that they want.
This article describes the Visual Index concept and tells how to create one for your document.
Benefits of Creating User Documents In-house
By: Barry Millman | 09/05/2007 | Non-Fiction
For small companies, creating their product's User Documentation in-house, provides benefits to the company, to (idle) staff, and to the product. This article describes the benefits and some downsides of producing User Documents in-house.
New Technical Writer: Avoiding the Interview-writing Disconnect
By: Barry Millman | 16/04/2007 | Interviews
Lost or garbled information is a terrible waste. Especially if it's the information you gathered from an interview and must now write into your User Document. Here's how to prevent that waste.
New Technical Writer: Don't Confuse your Reader With your Words
By: Barry Millman | 23/03/2007 | Writing
Stop confusing your Reader with the words you use. Your Reader is trying his/her best to understand how your product works without having to figure out your writing. Here are some writing guidelines to help you stop baffling your Reader.
Great Technical Writing: Improve Document Searches
By: Barry Millman | 14/03/2007 | Non-Fiction
Searches in User Documents (manuals, etc.) often fail because the Reader uses different words for a concept than the author uses. Since the Reader's words do not appear in the document, the document search mechanism cannot find them, resulting in frustration. This article describes a User-friendly technique for improving searches, without having to change the Users' behavior or the search software.
|
|
Writing 
