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!

Illustration of what Word's "borders" feature looks like

Figure 1. Mysterious lines sometimes appear in Word.

This isn't a purely hypothetical situation. In the various discussion groups I belong to, this kind of question turns up at least once per year, and sometimes far more frequently. Most people smitten by this problem try searching Word's online help to find out what just happened, but unless you already know the name for these lines, you'll have no luck finding any help. None of the obvious keywords (lines, line patterns, dashed lines, formatting, underlining, overlining, rules, watermarks) reveals the solution. "Border" is the word you should actually be looking for, but it isn't an obvious keyword; most people assume that borders appear on all sides of the bordered object, and don't realize that in Word, you can define borders for each of the four sides of a paragraph.

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:

Add an index entry for each word or phrase used in the interface. Most users see the titles of dialog boxes or the words used in a field or checkbox label, and can use them as part of their search.
Add any secret words that you and your colleagues use when you discuss the software's features. Those are the words your tech support people are likely to use, and the audience may use them too.
Add at least one synonym (preferably two) that users are likely to think up on their own.

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.

Example of embedding an icon in a procedural step

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.

Taken together, all these points that I've made also suggest an index-related suggestion so obvious that most of us never consider it: provide a visual index alongside the text index, and fill it with images of things that don't have obvious names but that are visually obvious. The last manual I read that provided such assistance (about 15 years ago?) was for the AmiPro word processor, which helpfully included a bunch of visual references that combined an image of the screen with a page reference so you could skim the index to find what you were looking at, then look it up in the documentation. This may have been in the days before "tool tips" (aka hovertext), or during the early days when they weren't easy to create, but it does lead me to wonder how many people have not yet learned that tool tips exist. I'd bet serious money it's far more people than we think, and that such people would love you for including a visual index.

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.