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’ll have a baffled Reader, resulting in dissatisfaction and expensive calls to technical support.

EXAMPLE: reverse osmosis water filtration WATER FILTER

I purchased and installed a reverse osmosis water filtration water filter. The instructions said to fill, and then empty (the instructions foolishly used the word “dump, ” which would have caused the destruction of the system) the tank.

The filter had a capacity around 100 gallons each day. Thus I expected the original fill (4. {5} gallon tank) to take less than 60 minutes. After about an hour or so the tank was still filling. Worried, I called the tech support team. I was told that it takes about two hours for the tank to fill.

One line in the User Documentation might have eliminated that call: “The tank initially takes 2 hours to fill. ” Unsure what to expect I, and perhaps other Users, wasted the time and money to call the tech support team line.

EXAMPLE: UPGRADING A ROUTER’S SOFTWARE

I had some problems with my Cable/DSL (Internet-Ethernet) router. The interior control panel caused it to be an easy task to search for and download updates to the internal software. The device told me that it would take a few minutes to check for updates (good), however it failed to tell me the length of time the update would take to perform once I downloaded the file.

Not telling the user things to expect when it comes to time is really 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 made a decision to wait longer to see what happened. It took a few momemts longer, and successfully completed.

It would only take a simple phrase such as “the software update usually takes up to five minutes to complete” to cut back the User’s anxiety.

PROGRESS INDICATORS (as displayed in a windowing environment) tend to be useless. Some rise above 100%, the others are logarithmic: they move quickly in the early processing and wait, seemingly by the end, for a long period while processing is completing. Consider making progress indicators connect with the time of operation, not number of files.

Some progress/activity indicators have nothing to do with the program they’re associated with. I have used virus checkers that have abnormally terminated, yet the activity indicator maintained moving. Make sure that progress/activity indicators do reflect activity of the associated program.

FILE DOWNLOADS DO IT

Telling an individual what things to are expecting isn’t a new concept. Have you ever downloaded files, the download site will frequently tell the length of time the file will need to download, based on your web connection.

EXAMPLE: YOUR PRODUCT’S INDICATORS

While most examples of “telling the user things to expect” deals with enough time needed to complete an activity, others may be related to the indicators and performance of the product.

I have a little smart battery charger with a red light for each of the battery positions. Unfortunately, the operation of the lights is impossible to comprehend, and there is no description of how they work.

Here’s what happens. When you initially 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 conclusion of the charging cycle the light may carry on again.

This is clearly confusing to the User. The User’s expectation is that after the light is out, the charging is completed. This might create a lot of User frustration, as Users would make an effort to use “charged” batteries which were maybe not charged. The developers of the battery charger should explain the operation of those displays.

UNDERNEATH LINE

Tell the Users what things to are expecting because they use your product. Often this information is the amount of time it may need for an operation to accomplish. For other products and services, 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 this will reduce your Users’ comfort together with your product, and increase your tech support team costs.