informativeMedia - In search of quality

Technical communicators try to produce high-quality publications. However, "quality" means different things to different people. And to complicate the picture further, perceptions of quality are not static; they change to reflect social trends, technical advances, and other factors. In this article, I consider some of issues that influence quality in technical documentation.

A geographical view

On my bookshelves, you can find a slim volume called Proofreading Plain and Simple, the work of Debra Hart May (see the full reference). She claims, and I have no reason to doubt her words, that every article in National Geographic magazine is typically reviewed four times by each of four proofreaders. These figures illustrate the effort needed to give a commercial magazine the quality that most readers take for granted.

This example reflects a pattern of quality management suitable for a magazine like National Geographic. The bulk of the quality-control activity takes place when most of the magazine's content is in an advanced state of development:

What do readers expect to receive at the end of this process?

A copy of National Geographic contains a series of unrelated articles with the text supported by excellent photographs, maps, and illustrations. Readers are motivated by a desire to be entertained and to be educated, but in a casual, undirected way. For example, they might enjoy learning about an expedition to the South Pole, but few, if any, would put their new knowledge to practical use. Magazine readers expect well-written text, but they are not upset by a certain amount of ambiguity or verbosity in the cause of literary style. They appreciate attractive photographs and illustrations, but they rarely analyse them critically.

The content of a magazine article is largely determined by the experience and the interests of its author. Readers' enjoyment of an article is unlikely to be affected by the decision of an author, or the editorial staff, to include or omit a specific item of information. To phrase this idea another way, the scope of an article is generally unimportant. Similarly, the scope of an individual magazine edition is also unimportant; the selection or omission of a particular article has no great consequence for readers. The situation is rather different with technical documentation.

A user-centred view

Rather than try to consider all types of technical documentation, I'll take the example of a set of printed manuals for a software application. The readers of these manuals—almost invariable people who want to use the software—do not have the same motivations as magazine readers. Instead they generally want to:

Consequently, the scope and the structure are much more important in technical manuals than in non-technical publications. The scope is largely determined by the breadth and depth of information that users need to accomplish all the tasks that the software supports. The set of manuals should be structured in a way that helps a user to find the information for any specific task as quickly as possible. So, as well the basic text and pictures, the content should include navigation elements such as tables of content, indexes, page headers and footers, and cross-references. Of course, these navigation elements can be useful in a magazine though their role is less crucial.

Most good technical documentation is "user-centred", meaning that it has been designed to reflect what users want to know and how users work both with the software and with the documentation itself. For technical authors to produce user-centred documentation, they must gain a clear picture of readers they are addressing. Whereas magazine editors can think of their readers as an anonymous market niche, technical authors need to understand their readers as a collection of diverse individuals. The needs of each reader depend on factors such as his or her:

Consequently, to serve their readers effectively, authors must carry out an audience analysis. In parallel, to understand how users will work with a product, authors must perform a task analysis. For example, they need to identify and classify all the possible tasks that a product supports. Some tasks might have to be performed daily; others will be performed only occasionally. Some tasks might be performed by the majority of users; others might only be attempted by experienced users. These observations suggest ways to organise a manual's content.

Together, the two analyses identify which information authors must provide for their users, and, just as importantly, they provide the framework for measuring quality. If manuals are user-centred, any evaluation of the manuals' quality must include user-centred criteria. Authors can only consider a manual to be a success if they can prove that it does indeed enable users to complete tasks correctly and efficiently. The only reliable way to make this evaluation is through user testing.

Projects producing technical documentation must often conform to requirements that are not directly user-centred. These same requirements also add criteria that must be considered in any quality-control processes. For example, a company might require documentation to:

Naturally, an implicit requirement of any project is that the resulting documentation has a professional appearance and is error-free.

The layout and aesthetic design of technical manuals usually appear simpler than the presentation you find in magazines. However, beneath the surface, the issues and relationships defining the content and structure are more complex. This complexity can only be managed through careful research, analysis, and planning at the start of a documentation project. No amount of copyediting can save an ill-conceived manual.

In search of quality

A geographical view

A user-centred view

References