|
–Geoff-Hart.com: Editing, Writing, and Translation —Home —Services —Books —Articles —Resources —Fiction —Contact me —Français |
You are here: Articles --> 2007 --> Complete information gets used
Vous êtes ici : Essais --> 2007 --> Complete information gets used
by Geoff Hart
Previously published as: Hart, G. 2007. Complete information gets used. Intercom February 2007:25–27.
It's become received wisdom that the documentation we create doesn't get read, particularly when that documentation is online help. That's true in the broader sense that we aren't writing novels, and nobody reads the information we produce for pleasure. But it's less true in the narrow sense that documentation fills a crucial role whenever a question needs answering and there's nobody around to provide that answer. When someone is forced to resort to our documentation to solve a problem, it's important that each visit to the manual or online help be fruitful. There are many criteria for what makes documentation successful, but one that seems in my experience to receive less attention is completeness. Each topic the reader consults must be complete—that is, it must answer all their questions on that topic.
What makes something "complete"? A complete topic meets four criteria:
Context explains where the reader has arrived and why they have arrived there. In short, it communicates the relevance of the found information so readers can quickly discover whether they've found what they're seeking and whether it will solve their problem. Readers lack the patience to read deeply to discover whether what they're seeking will be found farther down the screen if they scroll far enough or deeper into the chapter if they only flip enough pages. Thus, the first thing they read should tell them whether it's worthwhile making the effort. This means the title should not only be clear and specific, but should also be phrased in terms of the answer to the question that led them to that topic. One standard practice for headings of procedures is to use the present participle of the verb that most precisely defines the action, followed by a noun that defines the context for that action—Printing Web pages or Formatting your hard drive, for example.
Particularly for Web pages and online help, where scrolling is more disruptive and annoying to many users than flipping pages would be, it's courteous to start each topic with a miniature table of contents. Some authorities believe that this information represents useless redundancy, and that opinion is certainly relevant when readers can be expected to read, or at least skim; such readers will begin reading or skimming and continue until they reach their goal. But omitting that table of contents may pose problems when readers don't want to waste time searching and skimming—some want to know whether they've reached the right place before they scroll down or flip the page. A table of contents tells these readers immediately whether they're in the right place, and if the information is online, hyperlinking each entry provides one-click access to each part of the topic. Readers who are prepared to scroll down or flip pages won't be inconvenienced much by the table of contents, but those who are less patient will be inconvenienced by its absence and will appreciate the effort you save them by including it.
Another neglected form of context is information on where a specific topic fits within a broader context. For example, the topic Formatting your hard drive may occur in two very different contexts: In the first, readers may be installing a new hard drive or setting up their computer for the first time, and in that case, it's helpful to explain concepts such as partitioning a drive and choosing between the available file systems. In the second context, readers may be readjusting an existing hard drive, and will need to know about backing up their crucial data before they proceed.
What if the context you provided demonstrates that they've reached the wrong place? Provide navigational information about where they are and how they got there. In print, this consists of running headers or footers that communicate the current chapter and section. Online, "breadcrumbs"—a sequential list of all the links followed to reach the current screen, presented at the top of the screen—are a helpful tool because they not only show the current position within the information hierarchy, but also let browsers click on any of the links to "back out" and return to a previous point in the path to the current page. The "history" function of a Web browser or online help partially fills this role, but the information is concealed in a menu, where some users may not find it, and doesn't necessarily provide uncluttered information only on the path taken to reach the current screen. Think of breadcrumbs as complementary to the history function.
Also provide a list of related topics as cross-references, and hyperlink those topics if the information is being presented online. Time spent thinking about what might lead readers to a given topic reveals which cross-references you should provide. For example, readers might arrive at a topic entitled Formatting the page because they need to understand headers and footers and margins, or because they want to learn about paragraph styles (which determine what the page will look like inside the margins). That being the case, the current title may be insufficiently precise; Setting page margins would be better, and cross-references to paragraph indents, headers, and footers would be appropriate because each of these topics clearly affects where type will appear within the page margins.
Having confirmed that they've found the right topic, readers must now possess the necessary knowledge and mental skills to understand what they're about to read. The second aspect of completeness involves providing the necessary minimum background and theoretical knowledge that readers require to understand what they're about to read. In some contexts, you can safely assume that readers have already acquired this knowledge by the time they reach a specific topic; this is most often true for subjects such as mathematics, in which students must master concepts in a certain order to ensure that they've laid the foundations for understanding more difficult material based on those concepts.
Unfortunately, such situations are increasingly the exception. Where readers can arrive at a topic from any point of departure, as is the case for Web pages found through a search engine and online help topics found by consulting the index, we cannot assume that readers have the necessary knowledge. Our task then becomes one of identifying the prerequisites for understanding: What must the reader know to understand the current information? In the case of an online mathematics site, we know that readers must understand basic algebra before they can learn to solve simultaneous equations or study calculus; in a word processing help file, we know they must understand fonts and typography before they can define paragraph styles. Identifying these prerequisites can become quite challenging, since it requires us to understand the overall picture well enough to know where the current topic fits within that whole. This reveals any dependencies—conditions that must be met before proceeding. If we're unsure, it's wise to err on the side of safety and provide any missing knowledge or theory.
This can be accomplished by providing a brief summary supplemented by cross-references. The summary provides a refresher course for those who may already possess the necessary knowledge, and need only a reminder—or who don't need a reminder and don't want to be forced to scroll through many screens or flip many pages to reach the really important information. The cross-references expand upon this summary by linking readers with the more detailed information they may need to understand before reading the current topic. Since taking readers away from the current page to a distant location takes them out of their task, it may be worthwhile repeating the necessary information instead. This works best if you can expand topics within the same window to present more information, then collapse the topics again when that information is no longer necessary. Repeating text is also most feasible if you're working with single-sourcing tools, which let us write information only once and repeat it wherever necessary afterwards. It's also more feasible online, where storage is cheap and Web pages or help topics can be assembled dynamically; in print, repeating information can increase printing costs prohibitively. Nonetheless, repetition really may be the best solution in some cases.
Speaking of dependencies, procedural information sometimes requires a different form of knowledge or theory. For any step in a procedure, knowing where we are in the overall sequence tells us what steps must already have been completed by the time the reader reaches our description of the current step. If readers can reach that description without having completed the preceding steps, then clearly we must communicate that those steps must be done first. Apple's Mail program, for instance, provides a "Rebuild Mailbox" function you can use to update and correct the index for a selected mailbox to reflect its current contents; it's not at all obvious, however, that if you have multiple e-mail accounts that feed into that mailbox, you must expand the mailbox to show these accounts, then select the correct account before you can select the "Rebuild Mailbox" function. Unfortunately, when I first encountered this problem, the online help did not mention this prerequisite.
Sometimes it's necessary to provide a warning, such as "don't attempt this step until you've completed the previous step" or "you must have administrator-level rights before you can perform this step". Ideally, well-designed products will prevent you from proceeding before you've performed the necessary preliminary steps. For example, the Macintosh operating system requires you to remove a deleted file from the Trash before you can open it; this design feature works on the logic that if you're sufficiently interested in the file to open it, perhaps you should move it somewhere safe before you eliminate the file by emptying the Trash. But even well-designed products often permit procedures in which users can perform steps in any order; for example, in a word processor, you can define style specifications for a paragraph (font, leading, indents, etc.) in any order. Where that's the case, the problem we're trying to solve is not one of dependencies, but rather one of damage control or warning about unpredictable consequences. For example, if users of our word processor choose a leading smaller than the font size—something not permitted by all word processors—we need to warn them that type in adjacent lines will overlap. Our task thus becomes one of brainstorming any way that a probable action or series of actions could create problems or lead to unexpected behavior, and provide the appropriate warnings.
The first two components of completeness tell readers that they've arrived at the right place and provide the necessary intellectual tools to cope with the information they've found. The third component represents the information itself. Fortunately, this is where most technical communicators excel: explaining the steps in a procedure, organizing all the key criteria for making a decision into a flowchart, or presenting options and alternatives in a well-designed table. But the details of each step, criterion, or option may be lacking if we haven't carefully considered why someone will be reading the related information.
A variety of tools exist for determining what information must be present, ranging from developing use cases and performing task analysis to newer tools such as role-playing and the creation of personas. The solution in each case is to think our way through the task described in a topic, step by step, to ensure that we cover everything required for the task to be completed. In no case should we assume that information is obvious; all information should be made explicit rather than left implicit, although we may be able to provide cross-references to longer chunks of information rather than fully embedding that information in the current topic.
At the same time as we strive to provide all that detail, we must also strive to be concise and relevant. Conciseness does not mean that the writing should be telegraphic or that the number of words should be reduced to the absolute minimum; rather, it means that the material must be tightly focused. Conciseness also means that we should focus on reducing the number of words that must be read, thereby undermining the "there's too much to read" excuse. We can accomplish this only once we understand what information the reader truly needs to know, and what information is superfluous and can be provided by means of cross-references instead. To paraphrase Occam, we must make our writing "as short as possible, but no shorter". At the level of books or chapters in books, most authors start by creating a comprehensive list of all possible topics related to a subject, thereby violating the fundamental instructional design principle that you should start with a series of learning goals, and pick only topics that support the learning goals. At the level of individual topics, many authors do much the same thing, and provide all possibly relevant information rather than just the most relevant information.
The final component of a complete topic is one or more examples that provide confirmation the reader has truly understood what we presented. Examples are clearly required for documentation such as a programming language reference, but are often neglected in procedural instructions, where authors assume that the steps themselves are more important than their details. This may be true for experienced users who are reading the procedure solely to refresh their memory of the steps, but it's less true for users who don't understand the options. It might be excessive to explain the relative merits of ragged-right and fully justified type in a procedure for defining paragraph styles, but it would be fully appropriate to present examples of each, such as thumbnail screenshots, for those who would benefit from this information. Indeed, on the principle that a picture is worth a thousand words, combining the name of each option with a thumbnail image of the resulting page appearance would be more effective—and probably more space-efficient—than providing a purely textual description.
For information that deals with learning rather than doing, the examples may be closely linked to the context. For desktop publishing software, effective examples might include a series of images of page layouts, with callout arrows identifying page components such as headers and footers, paragraph indents, leading, and paragraph and character styles. Each of these callouts should be cross-referenced to the relevant section of the text—or hyperlinked if the images are online and can be formatted as clickable image maps.
The key to successful use of all these types of example is that each supports understanding of the main body of the information by providing a reality check.
Providing context makes information relevant or explains the situations in which a topic will be relevant; theory and background knowledge provide the tools for understanding information in that context; details and examples provide the remainder of what readers need to reach their goal. Information that is complete will be used because nothing is missing to prevent that use. When readers come to trust that you will provide complete information, that's one less excuse they have to avoid reading your documentation.
©2004–2024 Geoffrey Hart. All rights reserved.