STC Usability SIG Home
Back to the Newsletter

This article was originally published in the August 2009 issue (Vol 14, No. 3)

About the Authors

Debarshi Gupta Biswas has close to ten years' experience in developing technical documentation on different lines of business and for varied sets of audience. Currently, he is a Senior Technical Communicator at Cognizant Technology Solutions.

Suranjana Dasgupta has more than twelve years' experience as a technical writer. Currently, she leads the Technical Communication practice of the Kolkata (India) office of Cognizant Technology Solutions.

STC UUX Community Newsletter

logo70x50.gif (1973 bytes)
Usability Interface

Adopting Documentation Usability Techniques to Alleviate Cognitive Friction

By Debarshi Gupta Biswas and Suranjana Dasgupta, Content and Design Services, Cognizant Technology Solutions

The Digital Divide and Technical Communicators

In his famous book, The Inmates Are Running the Asylum: Why High-Tech Products Drive Us Crazy and How to Restore the Sanity, Alan Cooper, one of the greatest advocates of Interaction Design, introduced the term: "Cognitive Friction". He defined Cognitive Friction as "the resistance encountered by a human intellect when it engages with a complex system of rules that change as the problem changes. Software interaction is very high in cognitive friction".

This cognitive friction results in a digital divide between the software development community and software users. The digital divide, in turn, has a direct correlation with the usability of the application: how well can the software users learn and use the application or the product to perform their tasks and accomplish their goals. Today's Technical Communicators can help bridge this divide and reduce cognitive friction by applying industry-acclaimed usability techniques to the documentation they produce toward accelerating user acceptance of the product. Less cognitive friction means better user adoption that results in fewer calls to tech support, higher customer satisfaction, and in the long run, better brand loyalty.

This Article describes how documentation usability combined with heuristics can play a pivotal role in producing user-centered technical documentation that fosters a satisfying user experience.

Usable Documentation Accommodates How Users Think

Studies by Knowledge Solutions, a leading provider of knowledge transfer and end-user adoption solutions, indicate that the astounding figure of IT projects failing, late, or over budget could be slashed by almost a third if more attention was paid to user adoption. Gartner, the world's leading IT research and advisory organization, believes companies that spend more on application development but less on factors related to user adoption put projects at increased risk of failure. According to a study conducted in 2008 by the Sand Hill Group and Neochange, two leading consulting firms, the most critical factor for the success and return-on-investment of an IT project is effective user adoption.

Examples such as these have very interesting ramifications from a documentation perspective. Documentation can be effectively used to improve end-user adoption. Even the best software in the world with the most sophisticated features fails if people do not use it. And solid documentation can really help an unintuitive application overcome the challenge of poor usability. In a situation such as this, a Technical Communicator can suddenly become the most important player in ensuring the success of a product by assisting the users in performing their tasks with clear and crisp instruction-driven documentation.

Documentation that adheres to established usability principles, and that evolves beyond the conventional framework of detailed user's guides nobody cares to read, can go a step further in matching the users' mental model. This helps the users to find information quickly rather than following the wrong path and ending up frustrated. In his popular blog on the latest trends in technical communication, I'd Rather Be Writing, Tom Johnson writes:

"Invariably when I ask people how they prefer to learn new software, they respond, "I like someone to show me," or "I like to play around in the system and then ask a colleague if I get stuck." I've yet to hear the response, "I like long software manuals with lots of text in small print." Usually people that prefer this also like to slam their fingers in car doors and chew on tin foil...While your users are searching through the help, keep in mind another key factor in the help scenario: your user is frustrated. He or she is a little impatient, possibly angry, and the tension is building with each unsuccessful click".

In a nutshell, documentation should always address the correct emotional state of the users and should be predictable enough to point the users to the correct answer at their hour of need. Otherwise users would decide to wait on hold for technical support rather than leveraging the all-encompassing documentation to understand how a specific feature of an application works!

Heuristics for User-Centered Documentation

There is no cut-and-dried set of heuristic principles for evaluating the usability of documentation. Different opinionated discussion groups have come up with their own subjective list of usability criteria. the key and broadly representative findings. Following is a compilation that lists some of the key and broadly representative findings.

Documentation should match the real world

Cognitive scientists have studied mental models to understand how human beings make decisions in a variety of environments. Usability - the effectiveness, efficiency, and satisfaction with which users accomplish specified goals in a given environment - is connected to the mental model of the users to the extent that it predicts the action of an application as the users work on it. A classic example of how much the Human-Computer Interaction (HCI) experts have adapted the study of mental models to software usability is the simple Windows Calculator that has similar functionality and user experience to a hand-held calculator familiar to all of us.

Documentation, too, should be developed in such a way that it matches the mental model of the people that will use it to understand an application. Traditional documentation is based on the foundational assumption that users learn in a structured and linear fashion. Studies reveal that, while reading documentation, users do not follow a predictable sequence, do not read every word, and actually start acting on the information within a very short time. Increased usability in documentation design based on the mental model of the users has the potential to pay back handsomely in addressing the needs of these "impatient" users. To match the expectations of the real world, the documentation should have the following major attributes:

  • It should be designed from a deep understanding of the tasks that users perform. This understanding can be gained through interviewing representative users to determine what tasks they perform, what information they need to perform these tasks, what terminology they use to describe these tasks, and what prior experience and prerequisite knowledge they utilize to perform the tasks.
  • It should be well organized and properly chunked. This can also be achieved by interviewing representative users to understand which information is mission critical to them and which is less vital. Thus, applying information architecture techniques, essential topics should be placed at the top of the hierarchy, and the topics that contain less frequently used information should be placed at a deeper level.
  • It should transform long procedures into shorter, interrelated procedures so that the users can stay motivated to perform the tasks rather than being lost in an overly complex and detailed set of information.

    In his classic article, The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information, George Miller, the renowned psychologist, pointed out the limited capacity of our working memory in holding only about seven items or chunks of information at a time. This has intriguing implications for Technical Communicators. While developing documentation, they must take into account that users have limitations in processing information. To help users process information, documentation must let the users digest one chunk of information before forcing them to start dealing with the next one.

  • It should be based on a skeletal prototype that undergoes usability review by the users. Based on the review, the structure and content of the documentation should be modified to accommodate the needs of the users. Usability testing can unearth the search keywords that the users will use to look for information, the navigation pattern the users follow, and the errors they make while working with the application, which the documentation can then anticipate.

Documentation should go hand-in-hand with the product

As soon as the users see part of the user interface, they immediately set their own expectations on what to look up in the documentation. Here are a few items that can ensure that documentation meets user expectations:

  • If the users know that a piece of information is not available within the documentation, they will not waste their time looking for it. But, if they think that the information is available, yet they cannot find it after a period of unsuccessful searching, they are very likely to get frustrated. The documentation should have a well-designed index, one that contains key terms/concepts (and their synonyms), procedures, acronyms, abbreviations, and symbols used in the software. With the emergence of advanced techniques, like embedded indexing where a marker is embedded at each location in the document where a term is relevant, an index can act as a roadmap for technical documentation.
  • The procedural instructions and explanation of concepts should reflect the language of the software, reducing cognitive friction. In this context, Geoff Hart, who has held key positions at the Society for Technical Communication (STC), observes, "I still recall with considerable frustration trying to figure out how to type French accents in an early version of WordPerfect-none of the half dozen standard synonyms for WordPerfect's chosen keywords ("overstrike mode", if I recall) were anywhere to be found".

Documentation should be succinct

Usable documentation is always short and snappy. It provides information economically, but not at the expense of being incomprehensible, or omitting critical/useful information to reduce length. Documentation must be purposeful so that users get what need. In his article Heuristic Inspections for Documentation - 10 Recommended Documentation Heuristics, Vesa Purho sums it up wonderfully: "people working on a rooftop installing some hardware would not necessarily be delighted with nice multimedia CD-ROMs but prefer a laminated quick reference card".

To develop succinct documentation, Technical Communicators must understand their audience well enough to identify what their needs are, and predict how the users expect to accomplish their goals. The documentation should also provide the following:

  • Troubleshooting information to guide the users through common problems without ever explicitly stating that the workaround would not have been necessary if the software was properly designed
  • Alternative functions or tools, and scenarios in which to use them
  • Ensuring appropriate information is included, with references to additional help. In Geoff Hart's words, "if I'm using Web-authoring software, I want a printed URL or hyperlink that takes me to the W3C tag references page and accessibility guidelines so I can look up this information quickly. Why waste your time including this information in your documentation when an authoritative group has already done all the hard work for you?"

Documentation should be task-oriented and user-focused

Usable documentation does not describe the product in meticulous detail, and is structured around the tasks that the users are expected to perform within the application. It should be organized by a logical grouping of tasks presented in a language familiar to the users. Documentation should be developed using a structured process that starts with the big picture and adds lower level of details. It should be free from excessively complicated references to other documentation modules.

Additionally, the documentation must not forget to address the unique needs of every set of users. It should support users with varying levels of knowledge on the domain and tasks. Technical Communicators must understand the users' characteristics to successfully determine what documentation will work best for them. In her article, titled Developing Usable User Documentation, Rachel Campbell outlines the following checklist for developing a task matrix mapped to the user population:

  • List the tasks vertically, and the audiences horizontally.
  • Decide which topics are of interest to which users.
  • Analyze the matrix:
    • Is the matrix full of Yes's? Probably the topics are too broad to differentiate.
    • Are there empty rows? Possibly an audience has been left out.
    • Are there empty columns? Probably topics have been omitted.
    • If certain audiences only need a subset of the topics, an individualized document may be in order.

Documentation design should not be an afterthought

Standardizing the overall layout of documentation, especially in a multi-writer scenario, is critical to presenting information in a coherent form. Design acts as a means to an end: connecting the Technical Communicator that has information with the users that need it. Good design ensures that the users who will read the documentation can quickly get what they need to accomplish their tasks. Here are a few tips to ensure good and usable document design:

  • Provide visually distinct macro information zones and micro information zones for scanning and reading, respectively. The high-level headings form the scanning zone while the reading zone is a visually denser area, providing more layers of information.
  • Typography should pass the "Squint Test". While developing documentation, the Technical Communicators should ask themselves these questions: Which chunk of information is more visible than others? Which chunk of information gets lost? Are the chunks and overall structure of the page distinct?
  • Color should be used to command attention on critical information that the users must read, define specific foci, and identify what should take precedence.

Usability Testing for Documentation

In order to ensure that the documentation caters to the needs of its users, it must be safeguarded by a robust quality assurance system. Testing the usability of documentation is a practical solution to the documentation challenges faced by today's organizations.

Common Documentation Usability Testing Techniques

A document with a pretty look-and-feel that does not help its users accomplish their intended goals is frustrating for its audience. Here are a few common techniques that can be used as a litmus test to identify if a document is usable:

  • Observe representatives of the user population while they are reading the document, and question them to see whether they can perform tasks in a scenario-driven environment by following instructions outlined in the document.
  • Conduct surveys and questionnaires for users or business partners to gather their feedback on the document.
  • Apply a readability formula (such as the Flesch Reading Ease or the Flesch-Kincaid Grade Level) to determine if a document is suitable for its intended audience. Having said this, there are schools of thought that believe readability is driven by the perceptions of the individual readers, so a readability formula cannot be used to predict text difficulty.

Pilot Study on the ROI of Documentation Usability Testing

Elaine Ostrander conducted a study to identify the return on investment (ROI) with regard to documentation usability testing. The study was based on an over-the-shoulder usability testing of documentation, and formal laboratory study was not conducted. 11 participants from at least four different countries, with an average experience of over 10 years in usability testing, volunteered for the study. They were given a list of stages in usability testing, and asked to indicate the minimum, maximum, and average amount of time spent on each stage, and the corresponding hourly cost for each stage

The participants were also asked to report benefits of usability testing, although most of them could not quantify the benefits.

The study revealed that different stages of testing require varying degrees of labor and that the total cost of usability testing can vary widely. It also indicated that all the participants agreed on the following benefits of usability testing of documentation:

  • Decreased need for customer support to augment documentation
  • Costly errors created by poorly written instructions are eliminated

91% of the participants agreed on these benefits:

  • End-user completes tasks faster using improved instructions
  • End-user accesses information faster in final document

73% of the participants agreed on these benefits:

  • Increased customer satisfaction and loyalty due to quality of final document
  • Decreased need to rework before final publication
  • Decreased need to publish after-the-fact fixes

Although there was low response on a quantitative measure of each benefit, the study generated a strong indication that the return on investment for performing usability testing of documentation was too large to be neglected.

Conclusion

Usability is the combination of effectiveness, efficiency, and satisfaction with which the users accomplish defined goals in a given environment. User-centered documentation matches the users' mental model, thereby helping the users find information they want quickly and easily in their hour of need.

The list of documentation usability criteria is fairly subjective at this time, and various opinionated discussion groups have contributed to this. Usable documentation is based on a deep understanding of the users' tasks, and this understanding can only be gained through interviewing representative users. Applying information architecture techniques, the content within documentation should be properly chunked so that the users can assimilate the information properly. Procedural guides should have a well-defined and searchable index that enables users to connect key application terms to their correct context.

User-friendly documentation is always succinct, but never at the expense of omitting critical/useful information. It should be developed using a structured process so that it starts with the big picture and gradually adds lower level of details, addressing the needs of every unique group of users. Finally, the documentation must be tested among a representative group of users, and their feedback should be incorporated to make sure that it has met all of the major usability criteria.

Bibliography
All articles are property of the author or publication providing reprint permission. Reprinting this content in part or in whole requires permission from the source.
Go to STC Society Web Site
Home | About the Community | Activities | Resources | Topics
Newsletter |  Conference |  Bookshelf  | Toolkit 

UUX Community Contact List
© Society for Technical Communication