About User Documentation


Table of Contents for this Reading

About User Documentation. 1

Overview.. 1

The Topic. 2

About Documentation. 2

How To Get Your Product Returned Quickly. 6



Effective User Documentation is the second line of defense in saving your profits and pleasing your customers.  The first line of defense would be to create products which require no -- or minimal -- documentation; in reality, User Documentation can always benefit your User and hence benefit your product.

Documentation Helps Marketing.  The Tilley hat advertises that it is the only hat that comes with a four-page User manual (other companies’ hats have no User manual).  Tilley have been advertising that way for years...the advertising about the User manual must be doing something good!

We shall briefly define “User Documentation” as anything that someone produces to assist the User with a product.  It doesn’t matter if the documentation is a label on the product, a 500-page User manual, (includes) context-sensitive help, or is an Internet Website. If something is intended to help the User with the product, then we’ll call it “User Documentation”.

You’re taking this Course because you have to write User Documentation for some kind of product.  You need to tell a User how to do what he or she needs to do to be effective with your product.  You might have chosen this task yourself, or you might have had this job assigned to you.  It doesn’t matter.

By writing great User Documentation you achieve these benefits for your product and your company:

O     Reduce support costs: 1
The Users can solve their own problems with the product, instead of calling your Technical Support

O     Reduce support costs: 2
The Users can solve other people's problems with the product

O     Increase product value
Good User Documentation tells the User how to perform his/her tasks with the product, and provides additional information (for example as "tips") to make the User more effective with the product

O     Reduce User frustration; increase User satisfaction
Users get frustrated when they have a task to do and cannot determine how to perform the task; a good User Document helps them with their tasks

O     Enhance the image of your organization
It cares about the User


It is best all around if you do the best possible job in creating the documentation. Doing a good job will enhance your self-esteem and job value.  If the product does better, you do better.

You can learn to write effective documentation quickly.  This is the Course to do it!

This Course will help you create your documentation.  But it should do much more than that.  My goal is to get you to be as efficient and compassionate in providing great support to your Users as possible.  So we shall go beyond just the normal stuff about producing topic lists, ordering them, writing, grammar (we will minimize our contact with that topic, saving the grammar work for our editor) and so forth.  We’ll mention making your product an Internet Supported Product, and what that means.  We’ll describe the two-edged sword of “access” to the information you are trying to provide.

But most of all, by the end of this Course, you will be well on your way to writing the document that you have to produce for your real-life work.  As you progress through this Course you will actually complete the organization and sections of the documentation that you have to produce. After that, you will repeat the techniques you learn here to complete all the sections and subsections of your document.   So ideally, you have a project in mind.  With that, let’s start.

Disclaimer:  You are responsible for what you write.  Before publishing any document related to your organization or its products, it is your responsibility to get it approved by those in your organization who have the authority. 

Igetitnow! Training, Inc. and I cannot take responsibility for what you write or what you leave out of your document.  The liability for what you write and the way you write it is yours and that of your company.  Our liability is limited to the money you actually paid for this Course.


Let’s talk about User Documentation.

About Documentation

The purpose of User Documentation is simple: It’s to make the User of your product effective with your product. “Effective” means being able to use your product correctly, and safely. Good User Documentation helps the User receive the maximum value from the product.   Such documentation explains the features of the product, what needs of the User they fulfill, and how (and when) to use the features.  It also helps the User when things go wrong. 

Another way of saying this is that good User Documentation makes the User more comfortable with the product.  The documentation helps remove uncertainties that the User might have with the product.  Uncertainties breed discomfort.  Here’s an example:

Non-Drowsy or Anti-Drowsy.  I have a cold and I want to take some decongestants to clear the “stuffiness” in my nose.  The package says that the medication is non-drowsy (it won’t put you to sleep, so the User can function during the day).  I have no idea what that means, as there are at least two ways to implement something as “non-drowsy.”  One way is to use medications that do not have a side effect of causing drowsiness.  The other way is to use medications that will cause drowsiness, and then add some sort of stimulant to counteract the drowsiness.

 The problem is at night.  If the medication is made of non-sleep inducing components then I will be able to sleep when I take the medication.  On the other hand, if the medication contains a stimulant, it will keep me up during the night.  That’s not good.

The medication lists the components, but doesn’t answer the important question: Will I sleep tonight or not?  Thus its documentation fails, as it has not relieved my uncertainty about sleeping.  It did relieve the stuffiness.

As this example demonstrates the needed User Documentation not only tells how to use the product, but it also tells us about the product.  I wanted to know what the product would do to me as well as for me. 

I would like to expand the definition of “documentation” to include any (non-marketing) contact with the User.  For example, if you have a website which supports your products (a concept I strongly recommend), then the concepts we discuss in this Course will be relevant to your website.

Acme Airlines’ Extra Baggage.  My family and I were traveling via Acme Airlines to my brother-in-law’s wedding.  Our wedding gift was a painting measuring about 30 x 36 inches.  We needed to know if we could bring this along as baggage.  So I checked the Acme website, and found the correct page.

They said that the maximum baggage size was 80 inches.  After presenting this fact, they explained how to measure the item.  I found this presentation to be backwards.  If they had written the page correctly they would have something like:

We measure baggage as the sum of the length, width and height of a rectangular item.  By this measurement, the maximum allowable size for any item is 80 inches.

There are two other flaws with the information on the website:

· The maximum size should also be provided in metric units for those Readers not familiar with the inch. 

· They do not mention how to measure a cylindrical bag, such as a duffel bag or sports bag.

It’s amazing that something so simple could have so many errors in providing the information that Users need.  It’s also amazing that the writer of the website could rationalize that if the Reader read a few lines down the page, he/she would see how to measure their baggage.

Documentation is a very important part of every product.  Documentation enables the User of the product to get maximum benefit from the product.  One purpose of User Documentation is to counteract incorrect notions that your Users might have about your product.  Look at this example...

User Documentation to counteract previous experience.  Let me give you an example: a bottle of Hair Shampoo and Conditioner (a combined product).  There are no instructions on this product.  It seems like instructions would really not be needed.  Just wash your hair with the stuff. 

But that’s not all there is to it.  The product has a hair conditioner in it.  Now for most hair conditioners, the instructions say to work it into the hair and leave it for a few minutes before rinsing it out.  This could confuse the User: "Should I leave this stuff in, as I would with a normal conditioner?  Or do I use it as if it were plain shampoo (and rinse immediately)?" 

Uncertainty breeds discomfort.  Discomfort breeds unhappiness with your product.  Unhappiness with your product results in lower sales and higher (support) costs. 

An important goal of User Documentation is to reduce the discomfort that a User might have with your product.  By the way, the shampoo/conditioner bottle does list a toll-free number.  Some day when I have nothing to do, I’ll give them a call to see how to use their product.

A lesson from this example is that your User Documentation must be aware of and might have to overcome previous ideas that your Reader has about products like yours.  In the shampoo-conditioner example, the concept of “leaving a conditioner in the hair for a period of time” may interfere with the best use for your combined product.

Thus your documentation should deal with two aspects of the User/Reader’s history:

1.      Their lack of knowledge about how to use your product

2.      Their history that has taught them things that would interfere with best use of your product.

If you create a great product, and nobody can figure out how to use it (or they use it incorrectly or incompletely), then how “great” is your product?  This is very much like the philosophical discussion about a tree falling in a forest.  If there’s no one to hear it, does the tree make a sound?  You can be assured that there is no similar “philosophical discussion” about documentation.  If a product or some of its major features are unused because of poor documentation, the product cannot be “great.”  Think of the User Documentation as the final component that makes your product wonderful.

Documentation Separates the Failed from the Successful.  I bought a replacement battery for a cell phone.  I did the transaction over the Internet, and was amazed at the low cost and speed that the battery arrived. All I got in the package was the battery (in a plastic wrap) and an invoice. And it worked well for about three days.  Then it did not work at all. 

I replaced the battery with one from a local store.  The price wasn’t much different.  However, the local battery came with documentation about how to “condition” the battery.  You follow a specified plan of charging and discharging the unit to condition a battery.  If the battery is not so conditioned, then its life will be brief. 

The documentation made the second battery last longer.   The products were probably comparable; it was the documentation that separated the good from the mediocre.

Good documentation costs less than poor documentation.  If the product documentation stinks then the Users will have to turn to your customer service center to get answers.  That costs BIG, whether the contact is via e-mail or telephone. 

Good documentation adds value to the product.  In addition to enabling the User to get maximum benefit from your product, it adds psychological components such showing your enterprise cares about the User, and wants the User to be successful with your product. 

Good documentation helps the User to learn more about the product, and helps cure the product’s “warts.”   Every product has shortcomings (that’s one reason why there are future versions); I call these shortcomings “warts.”

Can You Flush a Toilet?  The Acme Wellsaver toilet is a low flush toilet; it uses less water than a regular toilet.  That’s better for the environment.  However -- and there were comedy televisions shows about this -- low flush toilets do not do the best job for large amounts of “solid waste” (their term).  It turns out that the Wellsaver has a hidden feature.  If you hold the handle down while flushing, you get more water in your flush; ideal for that solid waste problem.  Unfortunately, the “Homeowners Guide” doesn’t mention this useful fact.

A point in Acme's favor is that they attach a problem-solving sheet on the inside of the toilet tank lid.



Never Forget That Users are Selfish

Ideally, every product should be so simple, and so self-evident that no mistake could be made.  But that’s rare.  Even something as simple as a banana could use some documentation.  For example you, as a banana document writer, could provide recipes for banana delights; you could provide tips on how to ripen bananas more quickly and how to keep them longer.

Users want answers to their questions, and they want the answers immediately and in a form that they can understand and use.  For these reasons you, as a documentation writer, must always think from the User’s point of view, not from the point of view as an expert.  You must combine your expertise and knowledge with compassion for the User to produce great documentation.

Users rarely read your documentation from start to finish.  In fact they probably don’t want to read it at all.  They will try to use the product without reading, and then turn to your writing when they need help.  We will keep this fact in mind, especially when we discuss providing access to the information in your document.

Everything must be based on the User’s needs and the User’s point of view.  The greatest problem can be your assumptions that the User knows more than they actually do. 


          Hopefully, I have fired you up so that you are interested in producing good (or great) documentation.  Since I am writing this Course for you, I need to tell you what I think of you.

Documenting Toothpicks.  Toothpicks are a commodity item.  You buy them or you don't.  Why would someone write User Documentation for a box of toothpicks, and how would they distribute the document?  It seems odd to have a several page document attached to each box of toothpicks.

The document would exist only on the toothpick manufacturer's website.  A label on the box of toothpicks would advertise this with something like: Learn all about toothpicks: their history, tips for using them, best dental usage, toothpick trivia, history, and use around the world, how they are made, contests, 1000 uses for toothpicks, etc. 

My guess, and it's just a guess, that if a purchaser had a choice between two identical packages of toothpicks, the one with the mention of the website would be the one that gets bought.  Information has value; the toothpick with the website has more information, thus could have greater (perceived) value.

I've wanted to do an experiment to prove this (but have not had the time).  I would like to attach a pamphlet about how to shampoo your hair to half the identical bottles of shampoo in a store.  My guess is that the ones with the booklet would outsell the ones without the booklet.


(This is a what not to do section, as companies do not want to get their products returned.)

As a birthday gift I received an Acme digital (timer) coffee maker with an insulated carafe.  (The coffee maker is only part of the gift; the poor User Manual provided some fruit for this Course, and was the greater gift.) 

Most coffee makers with timers automatically shut off the warmer after about two hours.  However, let me quote (with the model numbers changed to protect the poor writing) from the User Manual:

Press the ON-OFF / TIMER button (electronic timer model T123) or the ON-OFF button (manual model M456) to turn the unit "off" when the carafe is empty or when the coffee maker is not in use.

When I read that statement, I inferred that I had to manually turn the unit off; the timer would not do that for me.  Other timer-based coffee makers automatically turn off after two hours.  Thus I wanted to return the device and get one that would automatically turn itself off.

This is a documentation flaw. The product has a "thermal" carafe that insulates the coffee to keep it hot.  Thus in reality, the machine turns itself completely off as soon as the coffee is made.

There was more.  The coffee maker came with some kind of wand that seemed to have a charcoal filter on the end of it.  But there was no mention of the wand in the documentation.  I took the wand to the store where the gift was bought and asked about this device.  The clerk called Acme who later returned the call, and the store called me.  The wand is some kind of filter to remove chlorine from the water.  There was no mention of the wand in the User Manual.  This led to wasted time (but no thought of returning the coffee maker).

It seems that companies are happier to modify and add components to a product than they are to document the changes.


I also have an Acme toaster.  The documentation for this device asks me to unplug it after each use.  That is not how I use a toaster.  I prefer to keep the toaster on the counter, plugged into the electrical outlet.  I do not have to unplug the Acme coffeemaker, my microwave oven, telephone or refrigerator.  I do not like the idea of having to unplug the toaster.  My question to Acme: is there a reason to have to unplug this device, or is someone being overly cautious.  I am confused about that point; I feel a bit unsafe.  The documentation (or product design) has failed me.  Perhaps I shall return it…

More about my Acme toaster.  It has an electronic toast darkness control.  Unfortunately, it does not toast an English muffin as dark as I would like, even at the highest setting.  This made me unhappy, until I figured out that if I pressed the "Defrost" button and set the toast control to darkest, it would toast the muffin as I would like it.  This would have been an excellent "tip" for the User Document.

In both these cases, it was a documentation failure that prompted me to think about returning the products.  Please keep in mind -- and keep it in the minds of those who design and manage product development -- that documentation is an essential component of the product and the User's satisfaction with the product.


Sorry, but I have another example (and there are many, many more).

I bought a beautiful Acme over the range microwave oven.  It is extremely nice, with many more features than I really want.  When I opened the box, the Installation Instructions were (where they should be) at the top of the package.  The first thing it talked about was the requirements for installation (excellent) and the "(Electrical) Supply Circuit and Grounding Requirements."

It said, that you must use a 20-Ampere circuit.  Wow, I was ready to return the device immediately.  My home has 15-Ampere circuits, except for heavy current Users like electric stoves and water heaters. I had just finished wiring in many 15-Ampere circuits in my kitchen.  So I was worried.

I installed the microwave, and tested it at full power with all accessories running.  No problem.

Inside, the User Manual said the microwave needed a 15-Ampere circuit.  And such a circuit seems to work fine with the microwave oven.  Why did the Installation Instructions specify a requirement that the manual denied?  Perhaps because they wanted the microwave oven returned.

One further point.  My house wiring is 14 gauge copper wire, which I use (industry regulations) for 15-Ampere circuits.  The power cord on the microwave oven is 16-gauge wire (which is thinner, and thus carries less current than 14 gauge wire).  How does this thinner wire handle 20 Amperes?  I don't know, maybe they want the microwave oven back.

Perhaps a competitor wrote the Installation Instructions.  I understand that many kitchens do have 20-Ampere electrical circuits; mine did not have them.  The microwave oven only needs a 15-Ampere circuit.  It works fine!


The message that we can get from these examples include:

O     Make sure your documentation is correct; that it matches the product it is trying to describe

O     Make sure that your documentation does not wrongly lead a Reader to think that there is something wrong with your product or that it is inferior to similar products, when it really is not

O     Make sure your documentation is clear and easily understood

O     This is complicated.  You may have a User manual that describes more than one version of a product.  For example, it may describe coffee makers with both glass and insulated carafes, and with or without a timer option. 
In these cases make sure that when the Reader is reading about a particular sub-product (such as a coffee maker with an insulated carafe) there is no possibility of confusion with the usage of the other versions of the product.  This is the lesson from the coffee maker example above.  The Acme coffee maker with the insulated carafe does not have to be manually turned off; yet the layout of the text suggested that it did have to be turned off.  The document should clearly specify which coffee maker it is describing for each of the operation procedures.

As you write your User Document with the guidance of this Course, you will (hopefully!) avoid these pitfalls.




Resources for Writing Great User Documents: Home

(c) 2006 Igetitnow! Training, Inc.