Great Technical Writing Tell Your Users What To Expect

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.




You Might Also Like:




No comments:

Powered by Blogger.