|
–Geoff-Hart.com: Editing, Writing, and Translation —Home —Services —Books —Articles —Resources —Fiction —Contact me —Français |
You are here: Articles --> 2007 --> Reader-centered documentation provides the necessary context
Vous êtes ici : Essais --> 2007 --> Reader-centered documentation provides the necessary context
by Geoff Hart, Fellow
Previously published as: Hart, G. 2007. Reader-centered documentation provides the necessary context. Intercom December 2007:22–25.
Far too many documentation projects start out with nothing more than a comprehensive inventory of the "widgets" used by a product—the menus, icons, and dialog boxes of software, or the switches, buttons, and levers of hardware. Although it's certainly true that each of these items will eventually need to be documented, the problem with this approach is that it focuses more on the tool than on the reader. As a result, it subordinates the reader's needs to the idiosyncrasies of the product, resulting in documentation that works only for a specific class of user: the relatively rare character who already knows how everything works and is only interested in finding out a few details. A feature-based approach is certainly appropriate for reference manuals, where the goal is to look up information on something the reader already knows. But it works poorly in user manuals, where the goal is to learn how to do something.
The large group of users who want to learn how to do something requires considerably more context than a feature list provides. The most inexperienced readers in this group are a particular challenge, since they need a broad overview of the context: what they can accomplish with the product, the main components that permit them to accomplish these goals, and how all the components fit together. More experienced readers already know something of this overall context, and instead need a more intermediate level of context that provides a more comprehensive view of the goals they can accomplish with the product. Lastly, all readers need low-level context, namely the specific tasks that must be performed in order to reach each goal. Below this comes the finest level of detail: the steps required to complete each task.
In this article, I'll discuss each of these contexts, with an emphasis on how each meets specific reader needs.
Consider a topic near and dear to our hearts: desktop publishing or (in more modern terms) document design. In this topic, the broad-scale context is the construction of documents. A simplified list of the high-level goals that users of this category of software might wish to accomplish includes the following topics:
Clearly, there are many more possibilities; this short list is designed solely to illustrate the concept of what constitutes broad-scale context. Each example in the list illustrates a large group of related topics that define overall goals of the product's users. Although most documentation does an adequate job of describing the software features used in each of these topics, the broad overview that shows how they fit together is often lacking: there is no discussion of when it might be necessary to break documents up into separate chapters rather than keeping everything in a single document, there is little discussion of what elements should repeat from chapter to chapter and page to page (and what ones should not), and so on. The documentation focuses too narrowly on tasks and procedures and in so doing, fails to provide the larger context (goals) that would help readers understand why they should perform the tasks and how each task fits within that understanding.
Having defined the broader structure of the document, the next step is to define the intermediate level of context for each of these groups: the tasks that, taken together, allow the user to accomplish a larger goal. Let's pick just one of the broad-scale topics from the previous section to explore how we can meet the reader's goal: designing an effective page. This goal has a range of components, which can be divided into two broad groups: the visual or graphical properties of a page and the textual properties of the page. The visual properties include the following:
The textual characteristics of the page include the following:
All these characteristics of page design are generally covered in adequate technical detail in most documentation; for example, each item in the Font dialog box is generally described thoroughly. What is often missing is an explanation of why each of the choices is relevant to the reader's needs. In the discussion of columns and gutters, for example, it would be helpful to explain how the choice of the number of columns affects line width, which in turn affects and is affected by type size and the required space between columns (the gutter). This would clearly lead us to include cross-references to type size, word spacing, line spacing, and other factors that affect legibility once a given line length has been chosen.
At the lowest level of our hierarchy of context, we must provide information that guides readers in their use of the tools and procedures that determine not just whether readers can use the product's tools, but whether they can use them effectively. Again, let's explore just one example from the list in the previous section to illustrate necessary context. Since typography is near and dear to the hearts of most technical communicators (witness the frequent, often-heated debates over the esthetics—or lack thereof—of Times New Roman), let's consider that topic. A simplified list of typographic topics for which context is necessary includes:
Again, most documentation provides complete knowledge of the available settings for each of these characteristics of text, but many fail to explain the uses of each setting and when each setting might be preferable. For most readers, who lack formal training in typography, it's useful to explain concepts such as legibility. For example, characters must be spaced sufficiently far apart that they don't merge, words must be sufficiently far apart that each cluster of letters is perceived as a single unit (a word) and not so close that two words overlap, and so on. This level of context should not become a treatise in cognitive psychology, laden with jargon such as saccades (eye movements from one fixed position, such as the end of a word, to the next fixed position); instead, it should provide gentle guidance on effective use of the tools. For example, some third-party books on desktop publishing software provide rules of thumb for effective choice of leading as a function of font size and column width, without ever delving into the cognitive psychology of how the eyes of readers scan to the end of the line and return to the start of the next line. The trick is to choose an appropriate level of detail.
The approach discussed thus far ensure that your documentation meets the primary goal of any documentation project: providing enough understanding of a product that its users possess the necessary intellectual tools to plan an overall approach to using the product, and can determine all the tasks necessary to attain each of their goals. But ironically, the problem with this approach is that by focusing so strongly on the reader, it may neglect the product itself. As a result, certain key features of the product may be missed, which poses an obvious problem when the user encounters a feature, asks how to use it, and is unable to find any information on how to do so.
The solution is straightforward: prepare a comprehensive list of product features and match that list to the reader-centered documentation structure that you've created through your consideration of context. Prepare that checklist of product features and match it to the broad-scale, intermediate, and low-level contexts that you've prepared to ensure that you have covered each feature. You'll undoubtedly find some aspects of the product that you missed by focusing on the reader, and some of these may become new topics at one or more of these three levels of context.
Other features simply won't seem to fit in anywhere—an unfortunately common occurrence when software is designed by marketing committees rather than through a careful analysis of user needs. Once you've ensured that a feature doesn't really fit well anywhere, you can create a separate place in your documentation (such as an Appendix) that provides the necessary information about this feature in a manner that doesn't interfere with your presentation of the more important material.
Note that by focusing on context in this article, I have entirely omitted any discussion of actual procedural information. Even the most reluctant readers will eventually learn enough context that they want to get on with the steps required to accomplish a task. To prevent readers from being overwhelmed with a sea of text that conceals the procedural information, clearly separate the context from the procedures. In an online document, this might be accomplished by means of hyperlinks. For example, a help topic on typography might begin with a series of related topics, such as a link entitled "Learn more about classical typography" or a series of links ("Learn more about: typefaces, space between letters, space between lines, [etc.]").
In print, which is inherently more linear, this might be accomplished by structuring every topic to contain a main heading (the task) followed by two main subheadings: the context (e.g., a heading such as "Basic elements of typography"), and the content (e.g., a heading such as "Applying typographic formats to text"). A very short introduction beneath the main heading, perhaps as short as a single sentence and certainly no more than a two or three sentences in total, provides the necessary context for how to use this part of the documentation. For example: "This topic explains how to format text. It begins with a discussion of the elements of typography, then concludes (on page 217) with detailed instructions on how to apply these principles." Conversely, you might choose to completely separate the contextual information from the procedural information. In that case, the topic might begin as follows: "This chapter discusses how to format text. For a discussion of classical typography, see Appendix 1 on page 340."
In this article, I've focused on an often-neglected aspect of documentation, namely the context that readers must understand (or be taught) before they can successfully apply a product's features. For many of us, there is no clear mandate to teach readers everything they must know about the environment in which a product will be used. Furthermore, it's simply not possible to provide the full context for any product. For example, graphic design is an entire college-level course, comprising many topics, each with its own textbook and hours of classroom instruction. It's clearly impossible for us to write all that course material ourselves and still accomplish our primary task: documenting a product that will be used by graphic designers. That's particularly true given that many of the audience for desktop publishing and other graphical software will have already taken that course and may know far more than we do about the topic.
In such cases, we instead must perform triage: Our goal is to identify the essential context that readers must know before they can use the product successfully, and it's this context we must provide. A seldom-used approach that makes this kind of triage more effective would be to include a bibliography of related works, and refer readers to that bibliography. For example, in the documentation for graphing tools such as the data-presentation tools offered by spreadsheets, we might refer readers to the works of Edward Tufte.
As in so much of our work, we must choose an appropriate compromise between too much and too little detail. In this article, I've provided some guidelines that should help, but the onus is on you, the communicator, to apply those guidelines based on an understanding of your actual audience's needs.
©2004–2024 Geoffrey Hart. All rights reserved.