Usability and Maintainability: Understandable Information

Tuesday, December 16th, 2008 | Technical Communication, Writing Theory & Practice

This post is part of a series on usability and maintainability. At first, meeting the needs of content consumers through usability can seem at odds with meeting needs of technical communicators through maintainability. My purpose in these posts is to discuss how technical communication best practices can satisfy both needs. I’ll use Gurak and Lannon’s usability criteria of users being able to “find what they need, understand the language, follow the instructions, and read the graphics” (A Concise Guide to Technical Communication, 31).

Simple Writing

A style of consistent, concise, simple writing benefits both users and technical authors. In the United States, the average adult reading level is judged to be 8th to 9th grade (ages 13 to 15), and I think it’s safe to assume that readers at higher levels comprehend writing at that average level or lower. (That statistic is cited as coming from the National Center for Education Statistics in a 2002 study, but that source is only referred to and not published online as far as I can tell.)

The simpler the level of writing, the easier for different writers to match the tone and style. Some technical concepts are difficult to explain in simple language, but keeping text in relatively short, simple ideas requires less rearranging and breaking up if the product changes. It’s nicer to be able to just delete a sentence or two and write a new one than to rearrange, break up, and merge existing sentences.

Clear, Consistent Terminology

Users can stumble over the use of synonyms if they’re not sure whether they’re referring to the same thing. Jargon causes a problem because users can tell when jargon is being used, and if they don’t understand it, they feel lost. And they feel like you’re talking down to them. Take, for example, an application I work on that includes a financial component. I’m not an accountant, and many of the people who will be using the financial component aren’t accountants, either. How is the user going to feel if he can’t get past jargon to get his job done? He could end up feeling both ignorant and stymied.

It’s easier for me when the project team and stakeholders have agreed on certain terms and if I stick to those terms. Therefore, it will be easier for someone who comes after me because she won’t have to decide whether different terms are actually different. She’ll know what terms to use every time rather than having to waste time deciding which word to use (or, having made a decision herself, going back through and standardizing the work I didn’t take the time to).

Further, for someone who replaces me, maintenance will be easier if I haven’t included a load of unexplained jargon in the content. Clear terms are important, and it’s important that when and how to use those terms be easily understood.

One of the most difficult aspects of ramping up for the project I was hired to work on was coming to understand the terminology that the application used. The application includes a complex data model that did not exist in the same way in the legacy application, so the designer and business analyst had to come up with a new set of terms. It took me a couple of sessions with the business analyst before it all clicked for me. Fortunately, my understanding became solid enough that I can explain the terms and how they related to a fresh set of people to their satisfaction within an hour. That has helped me to make sure that these terms do not fall into a “mystery jargon” category.

Previous: Usability and Maintainability: Navigable Information

Next: Usability and Maintainability: Instructions They Can Follow

Share This