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!

I Get By with a Little Help from My Tools

There is a risk that I might never see the sunshine again. I just discovered the "tablets" that attach to a computer to help the user create and manipulate graphics. They have a pad that works like a drawing board and an inkless pen that's really just another kind of mouse. Between the software that can morph my photos into "paintings" and the freestyle drawing and "painting" capabilities with the pen, I'm in heaven.

I sought out this tool as a practical matter. I wanted to create some personalized banners and other graphics for my blog, websites, and various documentation projects. Using a regular mouse to "paint" was, well, like serving soup with a bridal veil. It was just a plain mess! On top of the visual aspect, my repetitive stress injuries flared up like a bonfire. I see the purchase as an investment in my sanity and physical well-being.

It comes at a very good time, too. This new device is a great distraction from my job concerns. You see, I work for a financial arm of one of the big three American automakers...and we have not had a good week. In addition to worrying about just having a job, I have to apologize for the cluelessness of the people at the top of my food chain. It's embarrassing, actually. I walk around with dark glasses, a scarf, and a trench coat in hopes that no one will recognize me.

It's not like I didn't try to counsel them early on. For years, whenever they posted an announcement on our company intranet about one of the new overpriced, gas-guzzling, ozone depleting, carbon-spewing monstrosities in their line-up, I would post in our discussion forum a request for more compact cars with high mileage...an American version of the Prius, Honda Civic hybrid, or, dear heart be still, the Insight with 50+ miles per gallon. Their response would be a short blurb about the company investing in fuel cell technology...something that certainly won't be viable in the near future.

And I identified a need for a reality check when the CEO visited our small corporate offices in Pennsylvania a few years ago. As we saw co-workers going through the first of what turned out to be many lay-offs, this gentleman talked to us about the need to purchase the company's vehicles. He regaled us with a story about how his kids were just turning driving age. With all of the new cars he was buying to satisfy their transportation needs, he was running out of room and trying desperately to purchase his neighbor's property for the garage space. We were to empathize with him. I notified my managers of the necessity to provide this manager with some sensitivity training. Apparently, no one in Detroit received my message.

So, I immerse myself in things that keep me off of www.bloomberg.com and the Wall Street Journal site and from fretting over things I cannot control. These distractions include seeking out new opportunities and learning new skills.

Notice Anything Different?

First order of business was to redesign my blog. This blog was my very first attempt at blogging. When I set it up, I used a Blogger template and made a few changes that were facilitated by the functions in the Layout and Settings options. It was okay. I liked the green but I felt restricted by the template.

Let's compare. Here's a shot of the site on the first day:


While you can see what it looks like now, it will probably look different months from now. So here is a shot of the current view:


It's Not Just About My Opposable Thumbs

I started the redesign with a Blogger template (one called "Stretch Denim"). But the template was not quite the look I wanted.

To take it further meant learning how to use new tools. As I discussed above, I acquired a "tablet" to work on graphics. The tablet came with Adobe Photoshop Elements 6.0 and Corel Painter Essentials 4.0. Lightweight tools, I'm sure, for serious graphic artists but these are good beginnings for me.

For the banner, I created a rectangle and filled it with a gradient palette offered in Photoshop. The photograph is from a trip to Casa Loma in Toronto this past summer. Some cropping along with contrast, saturation, and highlighting adjustments in Photoshop gave it a new life to symbolize traveling a path - walking through a process, an experience, life in general.

The other tool I'm excited about is html - Hypertext Markup Language. When I talk to my S.O. ("significant other") about it, he looks at me sideways and tells me that my enthusiasm for html is further evidence that I am not cool and have no hope of ever being cool. But I don't care. Because, with practice and some more time working on my design sensibilities, I can use html to make my web material look great. While I could make a lot of the changes I wanted using the Blogger check boxes, there were some that I could not.

For instance, take a look at the statement in the banner. The heading is an ivory color while the mission is a dark blue. Blogger defaults to making both sets of text the same color. By adding just a little bit of html code, I was able to assign a different color to the mission.


I also had issues with the margin of the text in the banner. Blogger doesn't provide any tools to adjust margins. The text appeared over the image when I first added the banner. A couple of changes to the html code and I had this lovely left margin politely off to the side of the image.

Keeping It Clean

Other aspects of my redesign involved removing excess color. I've decided, after a lot of critical review of web sites and blogs, that I much prefer light or white backgrounds for text. Bold color is good when the site consists of primarily graphics. But a heavily text populated blog like mine needs more light colors. Plus, the big green margins on either side of the old design took up too much space and made each blog entry seem interminably long.

I kept the typeface simple - substituting Verdana for a serif font throughout the body but using Georgia for the top header to make it stand out. I may substitute another color for the green I used for visited links and dates. It could be a little hard to see.

I'd Like to Thank My ...

I received some very helpful direction from my design professor and classmates at NJIT but not everyone has access to them. (Too bad for you!) I also got a lot of useful information from:

• The wonderful tutorial that came with my tablet (a Wacom Bamboo Fun tablet). I was surprised at how helpful and thorough it was.
• A book called "Sams Teach Yourself HTML in 10 Minutes". It was amazingly helpful and broke out the lessons in easy to manage chunks. It has a prime spot next to my computer now.

For now, I'll look for some vitamin D fortified soy milk and force myself to take a walk a few times a week. Now that this door is open, I'm in real danger of becoming a hermit.

What Am I Supposed to Do About This...?

Possums are stubborn creatures. Most animals caught in a humane trap want nothing more than to get out and run when you open the door. Possums are not so eager. In fact, I've had to lift a trap, turn it upside down, and shake it until the little guy loses his grip on the metal mesh-like sides and tumbles to the ground. I'm not sure why they're reluctant to leave. It could be they somehow feel safer there. Or it could be that they figure there was food there so it must be a good place to hang out until more food arrives. Kind of like the reverse of an automat - instead of pulling the food out of a box, you walk into the box and wait for the food to be put in.

Catching wild animals like possums and raccoons is one of the risks of trapping feral or free roaming cats. I've caught my share over the years. It's a little unnerving the first few times. What do you do? Fortunately, I knew a few wildlife rehabilitators and only had to make a couple of calls to get rational and safe instructions. But most people don't have those resources or know where to start. In fact, most people who want to help stray cats don't know where or how to begin.

So, a few months ago, a friend approached me about developing resources for people who want to do something about the feral or stray cats in their midst. After doing some research and pulling together some materials, I started a website - kind of a "do it yourself" guide for people new to this world.

Why a Website?I decided to use a website for a few reasons:

1. The material can be accessed immediately...provided the person looking for help has computer and Internet access.
2. There's no postage or printing expense to get the information to the people in need of it.
3. The information can be updated quickly and without the waste of tossing outdated printed materials.
4. Audio-video material can be provided at a much lower cost than sending out video cassettes, Cds, or DVDs.
5. We can always print out material for people who don't have Internet access.

I see two main drawbacks to using a website:

1. We lose the personal contact that we would otherwise have if they had to ask us directly for the information. Sometimes it is useful to talk to people to prevent them from undertaking unnecessary or ill-advised actions.
2. It can be difficult to effectively format extensive, detailed material for web use, especially for older users. I believe this is the reason that so many paper manuals still pop up in the workplace. More on formatting below.

Getting Started

There are actually a lot of sites out there with information on helping cats. Most are focused on "TNR" or trap-neuter-return. They link to either national groups or groups in geographic areas outside of ours for support. While I don't want to reinvent the wheel, I think we can improve on the available material with better visuals and formatting; in addition, we're providing links to resources local to our area and information beyond TNR. After all, not all cats in need are feral.

What I've posted so far is very basic. Just a start, really. No useful visuals - yet. And the formatting could use improvement. My plan is to approach the design as a technical writer, making it easier for visitors to find the material they need and understand it. While I develop the site, I need to keep these five things in mind:

1. Audience
2. Components
3. Meaningful descriptions
4. Effective visuals
5. Format and organization

Audience

Who is my audience? What will they do with this information? How detailed do we need to get? And what type of language should we use?

It's essential to determine these things before starting out. Typically the person writing instructions has experience and knows the process. But how familiar is the reader with the process, tools, or terms often used by experienced people? Can I use words like "feral" and terms like "TNR"? Can I just say "set the trap" without explaining what a humane trap is, where to get one, or how to set it up?

I've already determined that I'm writing for people who haven't done this before. Sure, we might get visitors who know the routine and are just looking for the local resources. But our primary intent is to have a site to which we can direct people looking for help. They will use this site to help them make decisions and take actions to help the cats. We'll have to take time and explain the difference between "feral" and "stray" and how to make those determinations. Instructions will need to be thorough and detailed. "Set the trap" won't cut it. We'll need to take time to explain what a humane trap is, what the parts are, and how to set it. We will concentrate a lot on detail and concise language.

Components

In a technical document that accompanies a tool or appliance, components refer to the structural components - or actual physical parts - and functional components- or tasks and operations in the use of the tool or appliance. The audience determines what components you describe and how you describe them.

Components on my website consist of the tools used to help cats and the processes - with a heavy emphasis on processes. Step one - assess the situation. Step two - prepare to trap the cat. And so on. Because our visitors are inexperienced, we will - eventually - describe the steps in detail. Alley Cat Allies does a good job of this on their site:

Click on image to view text.

Meaningful Descriptions

Language used must be verifiable and precise as well as appropriate for the audience. Use of carefully chosen accurate terms and figurative illustrations help make the information meaningful to the reader. Defining the audience, as described above, guides the author.

In the examples I provided under Audience, I will want to define the term "feral"- probably with a link to a pop-up definition - because many of our visitors will not know what distinguishes a feral cat from a stray cat. Parts of the trap, such as the trip plate, will be described. For instance:

The trip plate is the flat, rectangular metal piece on the floor of the trap at the opposite end from the trap door. When the trap is set, the trip plate is elevated just slightly at an angle. When the cat steps on the trip plate, he pushes it down pulling on the lever which releases the trap door.

Again, we will need a lot of detail with plain language to make this site useful.

Visuals

Visuals can make nearly any instructional material so much more meaningful than words alone. They can show the reader what an object looks like inside and out, in its entirety or just part of it. They can be used to clarify descriptions, show relationships in size or proportion, illustrate relationships, or demonstrate hard to describe concepts. Photographs, diagrams, illustrations, charts, models, and videos can all be used to support the text.

This is where many of the sites I visited (my own included) fall short. Too few illustrations. While the Feral Cat Coalition's website provides some wonderful information, it's all text:

Click on image to view text.

Others, like mine again, include lovely pictures of cats. Some even have photos of cats in traps like Cat Snip:

Click on image to view text.

While Alley Cat Allies' site has very few visuals with the text, they do have a couple of slide shows and one very useful video:

Click on arrow to view video.

I will add illustrations of traps, photographs, and, I hope, video to supplement the text on our site.

Format and Organization

Instructional information is typically provided in some kind of sequence based on the needs and expectations of the audience. It can be organized in:

• Spatial order - where components are located in relation to one another; describes appearance and structure. An example might be a description of the different components of a humane trap.

• Chronological order - a sequence of events in time; describes steps in order of when they are performed. This could be something high level like

"Step one: Assess situation. Step two: Plan to trap. Step three: Set trap."

or something more detailed like

"Step one: Push lever in front of trap door and squeeze against door. Step two: While still squeezing, lift trap door so it is flush with the top of the trap."

• Priority order - describes components in order of importance. On our site, this might be characteristics for determining that a cat is feral.

How to present information on-line is challenging. Too many sites treat the screen as if it is a paper page. Organizing instructional material on the web so that it is easy to read as well as easy to access can be difficult. Clicking from one page to another to access next steps can annoy users. However, pages with a lot of text are visually unappealing, can take a long time to load (especially if there are a lot of graphics and the visitor has an older computer), and make specific information difficult to find.

I'm a fan of Information Mapping, also called Structured Writing, in my paper documentation. Attempting to adapt that format to web delivery (without the expensive training) has been on my to-do list for some time. In the meantime, I will seek out well-structured "how-to" sites.

Another option is to provide high-level information on the site with links to more detailed documents in .pdf or .doc format. This may be useful but could prove problematic for visitors without the appropriate software. Some users don't know how to find or download the necessary tools to open these attachments; others may be wary about downloading anything for fear of viruses.

Next Steps

So, the to-do list gets longer. While I know our audience, I need to concentrate on:

• Providing more information overall.
• Descriptive, concise language appropriate for my audience - including definitions.
• Adding meaningful graphics.
• Ensuring that I use the appropriate order for each description.
• Creating downloadable documents.
• Formatting the site so it is easy to use.
• And, lest I forget, adding instructions on dealing with those darn possums when they won't leave the trap!

Lots to do. But, it's for the cats so I can't complain.