You are here: Articles --> 2009 --> Visual and other indexes
Vous êtes ici : Essais --> 2009 --> Visual and other indexes
by Geoff Hart
Imagine, for the sake of illustrating a point, that you were working in Word, and a line suddenly appeared above the line of text you were typing. Figure 1 shows what this looks like. You certainly didn't tell Word that you wanted a line, so you try to select the line with the mouse so that you can press the Delete key and eliminate it—but try though you may, there's no way to select that line. Frustrating, to say the least!
Figure 1. Mysterious lines sometimes appear in Word.
The mysterious lines arise when Word helpfully applies a paragraph border style using the "autoformat as you type" function, which is set (by default) to automatically convert typed patterns such as ---- into lines or borders. If you're like me, and obsessively poke and pry into every nook and cranny of software to learn its hidden settings, you probably spotted this setting and either remembered it for future use or disabled it. Most users of Word aren't like us, and never learn this.
One thing missing from most software, not just Word, is a wizard or other program that will run the first time you launch the software, and that will then walk you through the process of customizing the software's configuration details. Any feature that works automatically, without specific user input, but that can be configured by the user, should be included in this process. In theory, that helps us learn about all of these features and control them right from the start of our use of the software. If you can't persuade the developers to design such a feature, you can at least include a topic on "things that will happen without you telling them to happen as a result of the software's default settings (and tips on how to change this behavior)".
At a crude estimate, about 1 in 1000 members per year of these discussion groups seems to experience the mystery lines problem, and writes in to ask about what happened and how to fix it. If your company sells only a few hundred copies of their software, that statistic probably doesn't represent a major concern. But if you're selling something as popular as Microsoft Word, which has millions of users, even that small percentage may represent several thousand people each year—and don't forget, that's a conservative estimate. Only a small proportion of the total audience belongs to discussion forums such as these, and an even smaller proportion write in to report such problems and ask for help.
The specific example we've been discussing has important implications for technical communicators. First, it's important to remember (and to teach the managers who control the documentation process) that search tools are only useful if the user knows our top-secret code words for a given concept. If not, even the best search tool in the world won't find the relevant part of the online help. If you have no other reason to justify devoting time and money to building an index, this unfamiliarity with our vocabulary is sufficient all by itself. Indexing is a highly skilled profession, and if you have the luxury of hiring a pro to do your indexing, that's great. If you don't, remember that even an amateurish index that is diligently prepared is probably better than no index at all. An effective, albeit suboptimal, index can be easily prepared as you write using nothing more than the software's built-in indexing tools and three rules:
This works adequately, if not optimally, for things that have obvious names, but not for things such as our mysterious lines. That leads to a second key point, namely that a surprising amount of documentation provides no way to look up the meaning of the things we see on the screen. Even when the authors provide a screenshot of the toolbars and palettes along with the names of each feature, it's not always easy to find that screenshot. When it is, you often have to open that Help topic each time you need to find out what something looks like. For example, I frequently have problems with Adobe documentation because they'll write something like "to fram statically, use the framistat tool", without showing me what that tool looks like or explaining where it's hidden. You certainly don't want to clutter your documentation with endlessly repeated redundant screenshots of menus, but you can at least replace "use the X function" with "open the [menu name] and select [name of the function]".
Better still, if the function will be activated primarily from a toolbar or other icon-based interface, provide a picture. Again, this doesn't have to be an inefficient full-screen screenshot. It also doesn't have to be an icon embedded in mid-sentence that radically disrupts the spacing, as in the top half of Figure 2. Instead, it can be an icon in the margin that provides a reminder of what to look for, as in the lower half of Figure 2.
Figure 2. (Top) Embedding icons in mid-sentence at a legible size compromises the legibility of the layout by increasing line spacing excessively. (Bottom) Moving the icons into the margin provides a clear, simple reminder of what the icon looks like, with a smaller effect on line spacing.
The omission of such useful aids from documentation happens for many reasons, some of which are beyond our control (e.g., insane deadlines that leave no time for such niceties). But one cause we can control and correct: most technical writers are word geeks and tend to forget that visual things are best described visually, particularly when there's no way to hold the cursor over something and wait for a text popup to tell you its name—as in the case of the border formats shown in Figure 1. Even a single "weird things you may see on the screen and what they mean" page would help, and I encourage you to think about how you could add such tools to your own documentation.
©2004–2018 Geoffrey Hart. All rights reserved