Concise Writing

Concise Writing. 1

Table of Contents for this Reading. 1

Overview.. 1

Additional Information is Good. 2

Additional Information 2: Overcome Functional Fixedness. 4

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:

You are about to Hibernate your computer.  Since Video Player is running, you may have to start your video again from the beginning.  Do you want to continue? [YES]  [NO]

What does Acme mean by “Do you want to continue?”  Does it mean:
· Do you want to continue playing the video?  [YES]  [NO]
or
· Do you want to continue hibernating your computer?  [YES]  [NO]

Acme’s writing confuses the User.  By adding a few more words (using one of the bulleted phrases instead of just “Do you want to continue?”), the ambiguity would have been eliminated. 

Do not get caught into the trap of thinking that your Reader understands your (overly) concise text.  If you need to add a few more words to make your message clear, then add those few more words.

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     Topic Information
This is the actual information that you want to tell your Readers in this topic.  I recommend that if possible you think up headings relevant to the topic instead of using “Topic Information” or “Educational Material” for the heading.  In the “Selecting Text” example I suggested that you use “Selecting Text,” “How To Select Text,” or “Selecting the Text” instead of “Educational Material” or “Topic Information.”
If the Reader is curious as to what happens, or is looking for tips on how to better work with the product or has some problems with this material, then he/she can read the “Additional Information” portion of the topic.

O     Additional Information

O   Tips

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.

O     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.
But what happens if the Reader has a problem, or you have additional information to provide about a topic?  Concise writing might suggest that you leave out that information.  But I disagree.

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.

Internal sounds can be considered User interaction points.  They should be explained in the User Document.  The manual for a frost-free refrigerator I once owned did explain the various sounds that can be expected from the machine.  That was a thoughtful touch to add.

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.

One day I was worried about the security of my main computer.  Could someone run the Handheld Simulator (which simulates the operation of the Personal Data Assistant), in it run the Password Manager, and thus see my data?  I found that when I ran the Password Manager for the first time, it let me pick a log-on password to run the software. 

Thus, I surmised, that if someone loaded the backup password files to the product, they would be able to see my passwords.

The good news is that the passwords were safe.  They were encrypted based on the log-on password (which becomes the encryption key).  Even if someone could run the program as I described, they would only see garbage, as the system would be using the wrong encryption key to decrypt the passwords.

The document could have added this text to calm the User's fears:

The Password Manager uses three files for dealing with your password information.  All of them are encrypted based on the master password (that you use to log onto the Password Manager).  Even if someone could copy your encrypted password files to another Password Manager, and use a different, but valid (for their) software master password, they would not be able to see your password files.  Your passwords are fully encrypted -- safe.

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. 
Provide the technical information that your Users may want and need.  Make that information easy to find.

"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.
ACM has a help website for its computers.  In that website they have charts relating to software upgrades for the various computers.  Here is how they label the columns in the charts: W40/p.
No a User looking at the chart might not realize that W40/p refers to both the W40 and the W40p.  The Reader becomes confused.  Now had ACM used this notation:
"W40/W40p", then there would be NO confusion.  Let's see, the no confusion writing (title) cost about 3 characters more.  There was plenty of space on the chart.  For a lousy 3 characters (on an electronic document!) ACM was happy to let their customers be confused.
Guideline:  If there is any possibility of confusion, ALWAYS spell things out.  The goal is "no possible confusion."

Why is watching a chef slice onions better than reading the instructions in a recipe? 

Because the recipe only says "cut onions in half and slice", while the chef shows how he/she cuts the onion in half (lengthwise) and how thick the slices should  be.

The recipe leaves out information that the Reader may consider to be important (whether it is or is not important).  This missing information causes stress in the Reader.