Please Don't Let Me Be Misunderstood

There's nothing more frustrating than trying to use documentation that you just don't understand. I'm going through that experience right now. My S.O. ("significant other") is having computer problems. A few months ago, his 4 year old computer crashed. Apparently, despite active virus protection software, it acquired some fatal disease that caused the desktop unit to look for a laptop battery. It is still not functional. As a stopgap measure, I loaned him my 6 year old computer that I had replaced recently before starting school in September. In all the time I had that old PC, I only had minor problems with it last spring when it started running painfully slow. I had it "tuned up" and, from then on, it worked like new. After only 3 months, however, he is having problems with it.

Diagnosis for the computer's demise: Teenagers!

He has two boys: 16 and 17. Despite warnings, they continue to visit sites and download material that they've been warned against accessing. They deny it but my S.O. continues to get suggestive invitations from young attractive women that point to the contrary. The latest dilemma is that the system does not recognize or cannot find Windows. So, I got my hands on a CD to reload Windows XP. Because I cannot access Windows to run it from the Start menu, I have to install it in the DOS environment - and it's been a long time since I've had to do something like that. Amazingly, I've remembered a lot but, regretfully, not enough. I visited the Microsoft website and the instructions are just plain useless to me. I searched the web further and nothing seems to help. So I am now off to talk to my friends on the help desk for assistance.

In the meantime, I'd like to say to Microsoft: "Invest is some better user readability testing. Not just with the techies - do some testing with folks like me. Or, better yet, people like my S.O. who don't even know what "underscore" is on the keyboard. All sorts of people are using computers these days and would like to be able to fix problems on their own. Work with us, will ya'?!?"

Do You Read Me?

I know of what I speak! For a good part of my career in mortgage banking, I've been responsible for creating user documentation - primarily policies and procedures along with some systems documentation and job aids. I learned along the way that not everyone thinks the way I do or learns the way I do. What to me is perfectly logical and clear can be convoluted or even gibberish to another person.

If the reader cannot understand and use the documentation, it's worthless. As individuals conveying complicated information to people who have to actually take action using that information, we must remember that we are writing for others, not for ourselves. Unfortunately, not everyone who writes manuals or explanatory material understands that.

How do we determine that our documentation is readable? That it can be understood by our intended audience? We need to test it!

Testing...1-2-3...Testing...

How do you test documentation for readability?

Well, there are several different ways and your best bet is to utilize a combination of them to achieve optimal results.

Things you want to look for in your testing:

• Ease of learning - How quickly can the user understand what she reads? Does she have to read and re-read several times to get it?
• Efficiency of use - How quickly can the user apply the material learned?
• Memorability - Once the user understands how to apply the information, can he remember it or does he have to frequently return to the documentation for a refresher?
• Minimizing errors - Does the user grasp the material or does the user consistently make errors even after reading the material?
• User satisfaction - Does the user feel that the documentation is easy to understand and helpful?

Doing the Math

There are mathematical formulas for testing readability of documents. There are the Flesch Readability Scale, the Flesch-Kincaid Reading Grade Level, and the Gunning Fog Index which use elements in text such as the average length of sentences and the average number of syllables in the words to determine how hard a document is to understand.

These tests can be done manually but that is no longer necessary. Software is available to test your content. In fact, you can test for both Flesch scores in Microsoft Word.

1. Click on Tools.
2. Select Spelling and Grammar.
3. Click on Options.
4. Under "Grammar", select "Show readability statistics."

When you complete your document, run Spell Check. After Word has completed the spelling and grammar checks, a dialog box will provide a report that looks like this. A score of "65" or higher for Readability is considered "plain language". The desirable grade level depends on your audience.

While these tests are good starting points to make your documentation more accessible, they do not measure things like whether or not:

• You've effectively communicated the information;
• The information is well organized;
• The format is user-friendly and the text is legible; or
• The content is appropriate to the users.

For that, you need to work with real, live people - representative users.

Tell Me What's On Your Mind

All of the mathematical equations in the world will not ensure that your user documentation is worth the paper or computer screen it's written on. In order to test that, you need to consult with actual users.

Select a representative pool of users. There may be many types of people using your documentation. Think about it. Ask around. Who needs the information?

In my world, I was primarily writing for people who took loan applications, processed loan applications, and prepared loan closing documents. But I quickly found that it didn't stop there. I also had state and federal regulatory agencies looking at the documentation to ensure we were giving our employees adequate and appropriate direction. Our legal department had an interest in it to support our position in litigation and customer complaints. Other internal departments, like Accounting, Loan Servicing, and Underwriting consulted it to understand processes and opportunities for improvement. So, it was necessary to consider all of these areas when documenting policies and procedures.

Ask your sample users to document their findings. They should consider various aspects including:

• Is the information accurate, complete, and appropriate?
• Does it flow and match what happens (or should happen) in the real world?
• Is the information presented in a logical order?
• Are the graphics appropriate, necessary, and consistent with the policies, rules, and processes?
• Would more graphic examples enhance the material or should some graphics be removed?
• Is the layout easy to use and pleasing to look at?
• Is the typeface legible? Does it need to be larger or smaller?
• Can desired information be located quickly?
• Is the language appropriate? Are there too many hard words or is the information too simplified for even a new employee? Are sentences too long or too short?
• Are there cultural, gender, or class biases?

Testers must be reminded to be critical and honest. And you, as the documenter, need to put ego aside. Don't argue over feedback. It can be tough to have someone criticize your work and tell you they don't like or understand your material. Taking a few steps back and looking at it from the user's perspective can help. Taking user suggestions will improve your documentation. Like I said, if they can't use it, it's not worth a thing.

Going back to the criteria under "Testing..." above, it may be useful to test your users' comprehension. Monitoring performance in the real world can also measure the effectiveness of the documentation.

It's Getting There That Counts

In the long-run, the goal is to create thorough, user-friendly, useful documentation. Your users will be happier. They'll also be more productive and efficient. (No more spending hours trying to figure out how to do it right!) Better documentation supports training and reduces the need for continued follow-up training. It also reduces calls to help desk or support teams and time taken by supervisors and managers to provide individual instruction.

And it will mean that your documentation will be used and valued. I was surprised when I found out just how many people in my organization used and valued the manual I created in my last position. A lot of the success had to do with the fact that I listened to my testers. I didn't always like everything they had to say but they were most often right. I handed over the documentation to others 5 years ago. It's surprising how little has changed. It was slightly reformatted but not so significantly as to be markedly distinguishable from the original. And most of the text remains the same. Better still, people still refer to it and actively use it.

I take a good bit of pride in that!