When Do People Use Documentation?

Remember the time you have got a new household electronics item (a microwave, an OTG, food processor, an electric cooker) or other gadgets like camera, ipod, smart phone, etc.  You usually spend some time with the product and its user manual trying to figure out how “it” works. Then you go back to it when you need to figure out how a certain feature functions or works.

The same applies to software manuals as well. Hence, we can say that manuals are usually used as reference material to understand a concept or product or to overcome the problem faced while using the product.

The users do not read the documentation before using the product. Nor do they read it in sequence, from start till the end. They use documentation as they use the product, especially when they:

  • Want to satisfy their knowledge.
  • Run into a problem when using the product.
  • Want to over come the problem and try for a work around.
  • Require information regarding a function/command to proceed with a given task.
  • Want to understand the theory behind the working of a certain functionality.
  •  Want to complete the task they are performing.

The sers outside the organization use documentation for making decisions. Those in the organization use the documents to track and maintain their own operation.

A Manuals Lament

– by Bob Moran 

I am a lonely manual. I sit upon the shelf.
I cannot help the user who will not help himself.

Sometimes I hear him dialing the help desk on the line,
and I want to cry out, Wait, the answers on page nine!

I try and try to tell them how friendly I can be,
but my voice is all but muffled by the plastic over me.

There are others up here with me clothed in this cellophane.
Our authors toiled long hours I wish it weren’t in vain.

Deep within our pages lies knowledge yet untapped.
You know that we could help you, if we weren’t so tightly wrapped.

Oh how I’d love to feel my binding against the desk,
my pages all uncovered, the plastic laid to rest.

The knowledge all exposed to the gaze of raptured
whose hungry search for knowledge cannot be disguised.

I’d work with them in unison to get the project done,
and then in quiet confidence wed start another one.

Oh, if only you’d expose my pages to your glance.
I’d give you so much knowledge, if you’d just give me a chance.


Grading Your Audience (Users)

You have to know for whom you are writing for and the degree of their knowledge about the subject. You have to adapt your writing to meet the needs, interests, and the background of the readers. You should perform audience analysis early in the writing process to help clarify how you should organize the information, write, and format your document. To understand the importance of grading and analyzing the audience before you start working on your document, let us consider the following cases:

Case 1: Writing a book—You are writing a book, Introduction to Computers.

  • What you do? You research the topic well and write it, adding a lot of technical information, graphics, and descriptions. You create a book that is technically correct, perfect in language and style, well formatted and designed document. The format and the design of the document is excellent too.
  •  What can happen? It can be rejected by your readers. The audience targeted were children of 6 years of age. They will not understand the technical concepts and hence the information will be of no importance to them. Also, the design and format of the book will not appeal to them!
  • What is the problem? The information is technically correct, but presentation and organization of the information, the level of detail you have to use, the language and style that has to be followed for these two groups of audience are entirely different.
  • Observation: For children in the age group 5-10, you have to include more figures and less text, use simple language, and less technical words. Even if you write a book with the same title for 15-year olds, the content and the structure of the book should be different. This shows the importance of knowing the educational background and knowledge level of your audience before you start writing.

Case 2: Writing a Report—Your organization has developed an electronics device that works as a pacemaker and is supposed to be a breakthrough in medical science. It is cost effective and the patient does not need to undergo a major surgery. You write a report about this new discovery in medical science.

  • What you do? You talk to the people who have created the product and get the required information. You then create a report about the functioning of the device and how helpful it can be to the mankind.
  • What can happen? Your report can be rejected.
  • What is the problem? You wrote for a general audience where as in this case, you have two different sets of users. One set of audience, consisting of engineers, familiar with the electronic concepts, but not with the working of the human heart. Another set consisting of doctors and people related to medical science, who are familiar with the matters of the human heart, but not with the electronics details of the device. Your report did not address the requirement of the two distinct and different set of users.
  • Observation: The two groups have different educational backgrounds and different purposes for reading about the device. The electronics engineers will be more curious about the electronics design and the doctors will be more interested in whether they can safely use this device to treat patients. So, you not only have to provide different background information and details for each type of audience. Ideally, you have to create two reports with different details, to captivate the interest of your audience.

Case 3: Writing a proposal—You are trying to persuade the management in your organization to buy a new but expensive documentation tool.

  • What you do? You research the product and create a proposal that describes the advantages of the software—what the product does.
  • What can happen? Your proposal can be rejected.
  • What is the problem? The information is technically correct, but you did not include the information the readers (the management) are looking for. Your aim is to convince the management that the new software is required for the work you are doing. So the proposal should have addressed the concerns of the management.
  • Observation: You have to justify how the new software can speed up the process. Also, mention how it will take care of the delays and other concerns where you currently spend a few staff-hours on a daily basis. Give examples of how the existing tools affect your flow of work and how the new tool can help you over -come these difficulties. Make a comparative study of the two tools.

Importance of Knowing Your Audience (Users)

Let ‘s begin with a story…

A salesman of a soft drink company was disappointed with a major failure of an assignment in the Middle East. A friend asked, “You are such a good salesman. Why weren’t you successful?”

The salesman explained, “When I got posted in the Middle East, I was very confident that I will make a good sales pitch. Since I did not know Arabic, I planned to convey the message using three posters in the order 1-2-3 and pasted them all over the place.

  • The first poster had a man crawling through the hot desert sand, totally exhausted and panting.
  • The second had the man drinking our soft drink.
  • The third poster showed him totally refreshed.

That should have worked,” said the friend. The salesman replied, “Not only did I not speak Arabic, I also did not realize that Arabs read from right to left. So my posters (which were from left to right) gave a different meaning altogether to the Arabs who were referring the posters in the order 3-2-1.”

So you see, it is very important to know your audience and their requirements! Else, inspite of having all the required information, your efforts in trying to get their attention or helping them will be futile.

The audience are the users who will be using the product and reading your writing. How you write and what you write basically depends on your audience. You have to analyze them to know about their requirements and how you can give it to them. Knowing your audience will help you understand them better and will help you determine the following:

  • The knowledge they have about the subject discussed in the document.
  • The terminology you should use.
  • How simple or complex your writing needs to be.
  • The tone you will have to use when you write. Tone, in writing, refers to how something is explained.

Example: Some marketing errors caused due to lack of audience analysis are listed here:

  • Coors used its slogan, “Turn it loose” in Spanish where it was read as Suffer from diarrhea.
  •  Scandinavian vacuum manufacturer Electrolux used the following slogan in an American campaign: Nothing sucks like an Electrolux.
  • When Gerber started selling baby food in Africa, they used the same packaging as in the US, with the beautiful Caucasian baby on the label. But, it did not sell. Later they learned that in Africa, companies routinely put pictures on the label of what’s inside the package, since most people could not read.
  • Colgate introduced a toothpaste in France called Cue. Unfortunately, cue happened to be the name of a notorious porn magazine in France.
  • An American T-shirt maker in Miami printed shirts for the Spanish market which promoted the Pope’s visit. Instead of “I saw the Pope” (el papa), the shirts read “I saw the potato” (la papa).
  • The Pepsi ad “Come alive with the Pepsi Generation” translated into “Pepsi brings your ancestors back from the grave“, in Chinese.
  • The Coca-Cola name in China was first read as Ke-kou-ke-la, meaning Bite the wax tadpole or female horse stuffed with wax, depending on the dialect. Coke then researched 40,000 characters to find a phonetic equivalent ko-kouko-le, translating into happiness in the mouth.
  • When Parker Pen marketed a ball-point pen in Mexico, its advertisements were supposed to have read, “It won’t leak in your pocket and embarrass you“. The translated advertisement read: “It won’t leak in your pocket and make you pregnant“. The company used the word embarazar which meant to impregnate.

Many years ago, I read somewhere that the academic subject most closely related to technical writing is acting. Then, I did not understand the significance of this statement. Now, I understand it very well. As you are aware, actors must be able to live the character they portray. They must be able to look as the character would, dress as the character would, feel as the character would, and react as the character would.

As a technical writer, you must have the same level of understanding of the person who uses the documentation you write for. You must know what your users know, what they don’t know, and what they expect from the product you are documenting.

Mistakes by Non-Writers: Lack of Audience Analysis

What is common knowledge to a subject matter expert (SME) may not be common knowledge to you or to someone else. Experts in almost any field have difficulty in explaining technical concepts to non-experts without using jargon. Language experts may know the concepts of grammar, but not the technical terminology or concept and may end up writing too much or too little.

Example: Think of how you would communicate with a 6-month old, a two year old, an eight year old, and a 15-year old. Even if you are communicating the same thought/idea to all of them, the way you do it is absolutely different. The tone, the voice, and the words used differ for each of them. You do it to suit the understanding of each of these persons you are talking with.

Documentation written by subject and/or language experts who do not understand the concept of technical writing may contain:

  • Too much detail of the subject for an expert audience.
  • Less detail of the product/subject for a novice user who expects detailed information on the basics of the topic.
  • Technical terms and the writing style used at the wrong levels of understanding.
  • Information what the writer wants to tell the users, not what the users want to know.

The right amount of salt and spices added to a dish makes it a great or bad dish. Similarly, the amount and type of information makes a good or a bad document.