Peter Morville’s subject of findability comes up all the time in looking for information on the web.
Yesterday I was seeking a driver for an old scanner. Should be easy. I had a serial number but not the model number. Unfortunately, the website contained no information about how to determine the model number. To access help/support about your scanner, you needed to know the model number. But how do you identify your model? Without that information, you are helpless. You aren’t allowed through this gateway of information without the right code, but you can’t give the right code because you don’t have access to the documentation.
Gateways are used to restrict access to telephone technical support, but they should rarely be used with documentation. Online help should provide paths for finding information, but sometimes if you are missing important information at the beginning, you are stuck. I like to tell the story about a Charlie Brown TV special. Charlie Brown is the football coach during halftime. All his friends are crowded in the locker room while Charlie Brown draws an extremely complicated football play on the blackboard. Finally, after Charlie Brown spends a minute going over his elaborate play diagram, he says, “Are there any questions?” Nobody speaks, until finally Pigpen says, “Are we the X’s or the O’s?”
Are we the X’s or the O’s? That is the perennial question for technical writers. Because Pigpen doesn’t know if he’s an X or an O, he can’t follow (or comprehend) the football play. To avoid these kinds of situations, documentation should offer cues right from the start about what documentation will cover and how to access it.
Web documentation does amazing things these days. It lets customers provide direct feedback and lets the company see exactly what search queries which customers are using. That makes it easier to identify information gaps and needs. Companies want to customize the web experience for the user. That is good. But if carried too far, it interferes with the ability to navigate through information.
Before you can document key features, the technical writer needs to address certain meta aspects of using help. How can the user access the documentation? How can the user verify that this is the right information? Which version does the user have? Is the information sought by the user out-of-date? Is the help intended to be all-inclusive (i.e., covering all sorts of scenarios)? Or is it merely suggesting the right way to use the product (while leaving the details to individual users). How does the user know he is at the right screen or pushing the right button? How can the user decide when to call customer service?
Technical support people often talk about the PEBCAC (problem exists between chair and computer). In fact, users are not stupid very often. Over the telephone, there are other problems:
- Users don’t know the terminology to describe the problem they have or to know what to look for.
- Users haven’t studied the problem long enough.
- Users don’t recognize details or signs which might aid in understanding the problem.
- Users might not have easy access to the documentation, may not be qualified to understand it (because of language barriers or technical level), or they may simply not have the time or energy to use it.
- Users might be unaware of the status of their computer/account/browser and/or they might be limited in their ability to obtain this information.
- Users might have received incorrect or misleading information from someone else, or they might have made incorrect assumptions about the product.
- Users may be familiar with one kind of product but lack the appropriate mental model for knowing how this product is supposed to work.
- Users might have previous problems in the past and found it easier just to call technical support than to risk aggravating the problem when trying to fix it.
In some situations, a failure to use the documentation stems from underlying defects in the documentation itself. They may not know what term to look up or be unfamiliar about how to search or be unfamiliar with the name of the action they want to do. It’s like telling someone who wants to spell something that they should look it up in the dictionary for the answer. Users have a general idea of the task they need to perform. They might be unable to identify what they want or what the problem is, but they can still provide reliable answers to questions based on observation. Under many circumstances, the best we can expect is for users to follow a checklist of tasks and seek help when this checklist isn’t met.
Documentation is often geared towards power users (those who are willing to use advanced features of anything). In the long run, documenting the main uses and even the advanced uses are probably where the technical writer should spend most of his time. After all, one doesn’t remain a novice forever. On the other hand, it’s vital to have insight into what questions are popping into the minds of novice users.
How then does one decide where to allocate resources? Here are some strategies and principles I have observed:
- Novice topics are the easiest to write, but the typical user usually doesn’t need them; they can usually figure them out on their own.
- Advanced topics/features should be covered especially if they are not obvious.
- It’s good to provide hierarchies of documentation for the beginning/middle/advanced user. It’s good to give users an idea about what topics to start with.
- Novice questions should include generous amounts of information about using help.
- Screen Captures. SW documentation is often reused for different versions of the same software. Therefore, it is important to minimize the number of screen captures you use. Why?
- Using out-of-date screen captures causes a lot of confusion.
- Replacing/updating screen captures is a lot of work.
- Unless it is difficult to do, screen captures should always be accompanied by a caption that explains what is useful and/or important about the screenshot. Instead of using the generic “Save As Dialog,” you should say “Ms Word lets you save in various formats” and then show the dropdown box of all the formats that MS Word saves in.
- Screen captures use a lot of real estate and generally shouldn’t be used for long topics. If there’s more than three screenshots on a single page, something is probably wrong.
- The best time to use screen captures in documentation is to reveal a non-obvious feature or to show what SW looks like when it is processing live data.
- Best contexts for using screenshots? : They are especially good for novice users and illustrating problem states in software.
- Screencasts are also becoming efficient methods for conveying the general sense of a user-interface. They are especially effective for quick tours and to illustrate the overall flow of work in a short period of time, but they still are no substitute for conventional documentation.
- Using Links. It’s good to arrange topics in a vertical hierarchy (a main TOC, with sub TOCs) to convey a flow of information from general to particular. In contrast, putting too many links in a single topic can confuse users — especially if the same links are repeated in multiple places. It’s good to have some redundant links, but often this causes users to visit them multiple times without really finding what they want. To prevent loops, the technical writer should:
- label links consistently in different topics. You can’t have a link on one topic go to yahoo.com and a link on another topic go to the best search engine in the world and another link to the only search engine company that discloses user information to the Chinese government.
- putting too many links on a single topic can dilute the usefulness of each topic. A link should appear only in contexts where there’s a good chance the user would want to use it.
- Automated indices and table of contents save a lot of time but generally provide an unsatisfactory user experience. Some types of information (such as glossaries and references) lend themselves to automation. With diverse content, it pays to spend time organizing topics hierarchically.
- FAQs are a great way to organize topics. But unless you’re just starting out, FAQs should be grouped in categories.
- meta-topics (“how do I locate the documentation?”) should be easily accessible from the first topic.
Here’s a dirty little secret known only to technical writers: many people don’t read documentation at all! Some prefer to learn by doing. Others may be troubleshooting exotic problems specific to their field. Others may find user forums and IRC a far easier solution (notwithstanding the irrelevant chatter). Some people prefer a learning-by-doing approach; other people may be troubleshooting complex (and esoteric) problems. Even so, good documentation increases people’s comfort level and offers people a quick high-level understanding of how something works. Also, it serves as a reference guide when technical support is closed and a software problem seems insurmountable.
Robert Nagle is a technical writer living in Houston.
