Overview
Incomplete User Documents disappoint your Readers. Two
attitudes of many Technical Writers result in incomplete User Documents. These
two attitudes are:
. "Everyone Knows That", and
. "The User Can Figure It Out"
This article describes these attitudes and presents methods
for overcoming them. The result is more effective User Documents and more
satisfied Users.
1. "Everyone Knows That"
The "Everyone Knows That" attitude makes
assumptions about your Reader's knowledge. These assumptions cause your Reader
grief.
Here's an example of a possible "Everyone Knows
That." Do you know this:
Tomatoes. Most of us keep them in a refrigerator. However,
storing them in a refrigerator will ruin the taste and nutrition of tomatoes.
Tomatoes should be stored on a kitchen counter at room temperature until they
are cut. Once cut, tomatoes should then be stored in the refrigerator.
Does everyone know that? What do you assume that everyone
knows about your product?
Sometimes your User Documents have to overcome previous User
experience. Everyone thinks that they know how to properly (safely) shut off a
barbecue...they don't! The safe shutdown method is described in most barbecue
User Documents, but it is not "advertised" (forcefully presented) in
the User Documents.
It’s rarely true that "Everyone Knows That". Just
because you find something to be obvious, it does not mean everyone knows that
something.
Here's another example: How do you use a (combined product
-- '2 in one') shampoo and hair conditioner? When shampooing, the shampoo is
massaged into the scalp and immediately rinsed. When conditioning the hair, the
conditioner is massaged into the hair and remains on the hair for about two
minutes. Now, what do the Users do for the combined product: rinse quickly, or
let the product remain in the hair?
If you have the "Everyone Knows That" attitude
when you write, you will tend to leave out needed material from your User
Document. You will be doing a disservice to your readers, and to your writing.
When in doubt whether "everyone knows something,"
assume that they do not. Then,
- add some text explaining the topic, or
- tell the reader where to find information that will explain the topic
Another Caution
Be careful about assuming that just because you explained
something earlier in your User Document, your Reader will remember (or even
have read) that information. It is rare for Users to read product documentation
from start to finish.
When in doubt, add a reference to that earlier (background)
information. Tell your reader where to find it, or provide a link to it if your
document is electronic.
Here's a Thought Experiment: You are a User of products: How
often do you read the product documentation from start to finish? If you always
do, then ask some other people. (The great thing about this fact -- that Users
do not read the documentation from start to finish -- is that it results in
great flexibility in writing, formatting and editing the product
documentation.)
2. "The User Can Figure It Out"
The User does not want to have to figure things out. The
User is not reading a mystery novel or any other literature, where he/she wants
to think about what is happening.
When someone uses your product, they are using it to meet
their own needs. Your product may be central to your life, but to your Users,
your product is a means to an end. And they do not want to have to decipher
your product documentation.
Here's a simple example. An e-mail tells you to call
someone, but the message leaves out the phone number. You are expected to find
the phone number on your own. The writer probably knew the phone number but
left it out. This "information oversight" gets expensive within a
company when the e-mail is sent to many employees...each looking up the phone
number on his/her own.
My favourite pet peeve: dates. Within recent memory, we
"survived" the Year-2000 transition. Yet we still write dates
sloppily. We use "06" for a year, instead of "2006." When
we see things like "07/11/04" what is the date it is referring to? Is
it November 4, 2007, April 11, 2007, or some other permutation of the numbers?
The standards for the format of dates vary around the world. This is an example
of both assumptions:
- "Everyone knows that" (because there is a "standard" date format -- there is not), and
Don’t leave things for the User/Reader to figure out for
themselves. It takes you only a few moments to include the material your Reader
needs and will save many Readers many hours in figuring things out.
Do It:
The writing literature tells you to "know your
Reader." Here is where you use that knowledge to improve your writing.
Either
·
find someone who is like your intended Reader,
or
·
"do your best" to act like your
intended Reader (you can do it if you need to)
In reading and evaluating the document, look for places
where
·
the writing assumes that "everyone knows
that"
·
the writing expects the reader to be able to
"figure it out"
·
the writing makes jumps that your Reader cannot
follow
·
the writing makes the assumption that the Reader
has read and remembered the entire document
Fix these places. It only takes a few words or sentences.
Everyone will be happier.
Comments