I really need to present my thoughts on concise writing. After all, all writing specialists as well as the Society for Technical Communications, strongly suggest that writing should be concise. But I disagree.
"Concise" means "to write or speak using few words." That I will agree with. For example, look at these statements:
1. What writing coaches tell you to do is to trim unnecessary words from your text.
2. Writing coaches tell you to trim unnecessary words from your text.
3. Trim the fat from your writing.
The statements say the same thing, but statement 2 is more direct, more concise and easier to understand. In this instance -- and many like it -- I agree with the authorities. Concise is better. There is absolutely no question. The wordier statement (1, above) says no more than the concise (more efficient) statement, 2, above. The wordier statement is more difficult to understand. (Statement 3 may have a bit too much jargon in the word "fat.")
Thus, in revising your document, you should work to streamline wordy, complex statements. Keep your writing short, simple and clear.
Beware! Do not make your writing so concise that it
becomes unclear. Here’s an example
from a screen display from Acme’s computer operating system. That system has a Video Player that can
play a downloaded video. If, while
the Video Player is running, you put your computer into a sleep (hibernate, a
temporary shut down) state, a message appears saying:
If concise writing eliminates what I call "additional information," then I think that the authorities are wrong. (The popular expression "that's more than they need to know" comes to mind.)
I believe that a User Document should provide as much additional information (which includes technical information, tips, warnings, and how to overcome product warts) as possible. Remember, one of my ideals for good User Documentation is that it should reduce calls to the product Technical $upport staff. By providing this additional information your writing can help meet that goal.
Leaving out information is only logical if you can assume that there will never be a problem in using your product. Is this a valid assumption? I think it is not, and therefore suggest that you provide the additional information that the User needs.
The problem then becomes how to prevent the additional information from getting in the way of the Reader's use of your User Document. As an example: if you are telling a Reader how to save a file (for a word processing program) and in the middle of your instructions you start mentioning something technical about how the file is saved, then you may confuse the Reader with the additional information.
I look at Additional Information a User Document as a second roll of toilet paper in a washroom. It’s there when you need it, and almost invisible when you do not need it.
The solution is to use the Tiny Topic Templates that I suggest for your writing. I strongly suggest that for each topic (except perhaps for the lowest level ones) you are writing about you have the following headings:
O Overview (or Background or Introduction)
O Describes the topic, who it’s intended for, and what the Reader may need to understand it
O Where to get background information
O Additional Information
O Alternative ways of dealing with the topic
O Possible Problems and their Solution
O Technical Information
O Other Related Information
By using these headings the Readers can easily find the information that is relevant to their needs, and skip what they do not want to read. Thus the additional information is present, but does not interfere with their reading.
The headings for the sections are the key to successfully adding additional information into your document. By using meaningful headings the Reader can easily choose what text to read for a topic.
O The Overview heading tells the Reader what the topic is about, how it will be covered in the following text, and what he/she might need to know (and where to find it) in order to deal with the topic. I have presented much about Overviews and their need in this Course.
The Topic Information heading tells the Reader
what he/she should know or do in order to deal with the topic. This is where concise writing would stop.
O The Additional Information heading (and subheadings under it) identifies text that could be of use to your Reader. The Reader will see the heading and read on or skip the material as appropriate to him/her.
Acme PowerStation internal fan. The Acme PowerStation manual does not
mention this fan anywhere in the manual, even though there is a section on
“overheating.” The User’s response to
the operation of the internal fan is “what’s that noise?” followed by some
concern (because of the uncertainty) and a search in the manual.
One final point about the headings. If you do not have information for a heading (for example, no additional information), then leave the heading out. Don't write something like Additional Information. None. That looks too mechanical and wastes space in the document.
We will spend some time later in working with headings in order to provide effective access to your document.
Acme Password Manager Software Leaves Out Important
Technical Information. I have the
Password Manager software, and I run it on my Acme Handheld Personal Data
Assistant. All the information in the
Handheld gets backed up onto my main computer.
Users Need Technical Information! Acme’s Webscrape and E-mail program stores
various files for its Users. These
files include an Address Book, saved e-mails, Internet Bookmarks, etc. Acme makes it almost impossible to find
where these files are stored on the User’s computer. However Users need this information in
order to back up this useful data.
"Functional fixedness" is a trait of most people. It is the situation where you see an object, and that object has a fixed function. Many people find it difficult to use objects for purposes other than their fixed function.
Wikipedia has a brief article on this, and provides the example of someone needing a paperweight but only a hammer is available. Due to functional fixedness the people do not see the hammer as a paperweight, only an object to hammer.
Thus Functional Fixedness refers to the situation where someone is locked into one way of seeing or using something.
How does that apply to us? And to "Additional Information"?
Very importantly, as this example will show.
I have an ACME wrist Global Positional Satellite (GPS) Tracker. I use it when I hike or walk. It tells me things like my speed, position, etc.
Notice I said "ACME wrist Global Positional Satellite (GPS) Tracker." I used it in winter, thus I was wearing a heavy jacket. As a result using the device on the wrist was a real bother. My jacket was tight around my wrists, and it was difficult to get to the Tracker.
Wrist, wrist, wrist. It goes on the wrist. Aha, but it also works perfectly in my pocket. Thus (through a burst of brilliance) I decided to put the device in my pocket, rather than on my wrist. It was much easier to use, and more comfortable.
The functional fixedness made me only think (initially) of putting the device on my wrist. I consider myself lucky to have thought of the pocket.
However, if ACME had included this tip in the User Document, I would have been smarter from the beginning:
TIP: The Tracker works well in a pocket. If you are using the Tracker in the winter, or any time you are wearing a tight jacket or otherwise find it uncomfortable to use on your wrist, just put the Tracker in your pocket.
Helping your User over his/her functional fixedness will create a better experience with your product.
Another Word Wouldn't Hurt. I am really angry about this.
ACM, the computing arm of Acme has two computers with similar model
numbers. One is the W40 and the other
is the W40p. Obviously there is some
difference between the two or else there would not be the expense incurred by
ACM to keep track of two separate model numbers.
Why is watching a chef slice onions better than
reading the instructions in a recipe?
(c) 2006 Igetitnow! Training, Inc.