informativeMedia - In search of quality

When corporations develop commercial software for the mass market, they often claim to put considerable effort into testing documentation to ensure that it actually assists users. In my experience, documentation is rarely user-tested on small projects. Instead, especially if time is short, quality control is usually restricted to reviews that focus on technical accuracy and correct grammar, punctuation, and page formatting. Managers like this combination because the technical authors and technical personnel already on a project can perform these checks. By adopting this strategy, managers avoid having to find and organise external people, with the additional costs this incurs. However, reviews generally do little more than catch minor errors and to add some superficial polish to documents.

If we consider the English language, a large proportion of native-English speakers (including many who have tertiary education) do not clearly understand fairly standard grammatical rules such as the different roles of "that" and "which". Similarly, many people are uncertain of the accepted rules for using punctuation. Consequently, these people are unlikely to notice, or be misled by, minor faults in grammar or punctuation. Also, errors in page formatting, even if they are noticeable, generally have little or no impact on users' ability to understand the instructions on a page. I am not suggesting that authors should take a sloppy attitude to grammar or formatting. However, they should not delude themselves about the true usefulness of reviews, which should be used to complement user testing not to replace it.

I think that authors often fall into the trap of spending an excessive amount of time polishing manuals simply to avoid criticism, from colleagues or employers, for clearly visible but minor mistakes. Colleagues seem keen to notice and report typographic errors, but more important failings—such as the omission of vital information—are more likely to go unnoticed until a product's support desk starts receiving users' calls at some later date. Another reason for technical authors concentrating on superficial quality is that they sometimes lack of a solid benchmark against which they can evaluate the information they provide. From my contact with the IT world, it seems fairly frequent for a development team to work without a complete, up-to-date requirements document or functional specification. It is hardly surprising, therefore, that technical authors sometimes struggle to compile a comprehensive and reliable task analysis.

Issues with online help

So the types of quality-control processes most appropriate for developing printed technical documentation are rather different from the processes that are suitable for publications such as magazines. When authors publish technical documentation online, they must consider additional quality criteria.

One of the most common methods of publishing technical documentation online is to develop online help. This medium is different from printed pages in many ways. One of the key issues for users is that they cannot easily understand the volume and organisation of information is hidden away inside a help file. They cannot skim through a whole help file in the same way that they can leaf through a manual. Instead they rely heavily on features such as the table of contents, index, and search function to find specific information. Because of users' reliance on these navigation aids, it is particularly important that they are careful evaluated in any quality assessment. At one conference I attended, a speaker stated that it took many person-months of effort just to develop the index for the online help of a Microsoft office application. This might seem excessive—certainly to any project managers reading this—but research has shown that many users use the index as their normal starting point when working with online help. If the index is inadequate, users will fail to find the information they need.

In an online help file, information is tied together by various forms of interactive links:

All these links need to be tested before the software and help are distributed. Broken links demonstrate in an unequivocal manner, even to the most casual observer, that testing has been inadequate. So authors tend to pay particular attention to testing all types of links. Clearly, help text, no matter how well researched and written, is useless if users have no way to navigate to it.

Overall, a medium such as online help underlines the difference between technical documentation and other types of publications. With online help, quality-control work needs to place a greater emphasis on evaluating the navigation aids and other structural features in a file rather than the details in text and graphics.

Web issues

At first consideration, web pages might seem like just another hypertext publication medium not so different from online help. However, when technical authors publish on the web, they must address additional technical and cultural issues. Of course, the Internet is by no means the preserve of technical authors. It hosts a great diversity of information published by all types of organisations and contributors, and it is the Internet in its entirety that colours users' ideas of what constitutes a "good" web site.

When developing web sites, technical authors' greatest frustration is the relatively poor control they exert over the presentation of content they develop. Amongst the many problems that confront them:

The only easy response to all these issues is to accept a compromise. Both authors and readers have had to accept that the reliable presentation expected in printed publications cannot be reproduced on web pages. By careful page design and programming, authors can limit the problems to a degree, but some users will not see what the authors wanted them to see. Fortunately web users are fairly tolerant of formatting problems because they are a common feature of the web at the present stage of its evolution.

There is a growing call for "accessible" web sites, where everyone has equal access to all of a site's information and functionality. Although accessibility addresses many different issues, one concern is to aid web users with visual disabilities. These people "view" web sites with the help of screen reader programs that convert text to synthesised speech. Screen readers raise a whole new set of design and test issues that are not faced by anyone publishing on paper. A blind person using a screen reader perceives the organisation of a web page very differently from a person with no disability. Unfortunately several different screen reader programs are in common use, and each interprets HTML markup differently. Naturally, any quality control of accessible web pages must take into account these differences. Developing an accessible web site is currently something of a black art even though authoring tools are starting to include features to assist authors.

For technical authors, technological developments are usually a mixed blessing. On the positive side, they can bring new ways to distribute and present information to users. However, simultaneously, they bring unwanted distractions. Authors often spend significant amounts of time dealing with technical problems rather than on developing the information that users need. Consequently, technical authors tend to be relatively conservative, avoiding unstable, cutting-edge technologies. However, web technologies are now so ubiquitous that authors are increasingly obliged to use them. The greatest challenge in producing high-quality online publications is how to take advantage of technology without becoming its slave.

In search of quality

A preoccupation with the superficial

Issues with online help

Web issues