Database Reference
In-Depth Information
The body text of the user manual should not be text heavy, meaning it should not contain paragraph after
paragraph of information. Writing a few paragraphs about the program itself can be valuable, but be sure that
the majority of the text is broken up into categories such as numbered lists, picture illustrations, bulleted lists, a
sidebar, a note that has a different format as the rest of the text, and so on. A very well-written user manual can
give the necessary information at a glance.
■
At a glance, at a glance, at a glance…notice a pattern? The faster users can glance at the instructions, gain
the information, and move on, the more productive they are, the happier your client is, and the more effective your BI
solution will be.
Tip
You may have heard the
hand
rule. Although this is not the official name for it, the essence of it is this: if
you can put your hand on the printed page in any place and your hand does not touch something other than
paragraphs of text, then your text is too heavy. The reason why this is important is because users cannot find
information easily in a block of heavy text. When the text is broken up, your users can navigate through the
instructions much more easily, enabling them to visually skip around on the page and gather information faster
and more readily find what they are looking for.
As we stated earlier, our exercises are similar to how a user manual's instructions should appear. The voice of
most of our exercises, however, is not always in the imperative in this topic, which is the recommended voice for
a user manual's instructions. (One exception to this is the next exercise. Exercise 19-1 is written in the imperative
and has the proper format and voice for a user manual.)
Here is an example of an imperative voice and a nonimperative voice:
•
Imperative voice:
“Click the OK button.”
•
Nonimperative voice:
“After that, you can then click the OK button.”
The imperative voice begins with a verb, is in the form of a command, and the word
you
is implied. The
second example is simply a statement and is less effective for instructional documentation.
Keep the instructions precise and properly spell the titles of the items you are referring to within your
program, paying attention to capitalization. If the button title is OK, for example, then the instructions should not
say, “Click the Okay button.” (In other words, Okay should not be spelled properly when the
OK
on the button
itself is not spelled out properly.) Nor should the instructions be “click ok” or “click Ok” when both letters of
OK
are capitalized within the program. This may sound nitpicky, but you would be surprised how users can get
lost when the instructions within your manual are not capitalized exactly the same way that they are within the
program. (You may not be so surprised by this, however, if we have made that mistake within this topic and you
found yourself lost for that very reason!)
Your instructions should also be free of filler words. Descriptive words are helpful, but get to the point of
what needs to be said as quickly and concisely as possible without losing the reader.
Figures
Whoever said a picture is worth a thousand words had the soul of a writer—perhaps even a technical writer.
Figures are the illustrations or pictures in your manual and can be one of the most important signposts you use.
They save the writer a lot of words explaining what to look for within the program. Figures help tell the story
and aid the user by giving clear and precise visual cues as to what they are to click or where an item within your
program can be found.
If you have ever shopped at Ikea, you may have noticed that some assembly-type user manuals do not
contain words. The illustrations themselves are the instructions. Sometimes these illustrations are easy to follow,
and sometimes they are worthless and get thrown away with the box the product came in. Make sure that the
