Two questions any writer must deal with are: “What do I write about?” and “How much do I say about it?” Essentially, these questions deal with the scope and the depth of a document. Technical communicators have a tendency to want to document a topic as completely as possible, and we carry this instinct with us when we architect and write Help files. In this column, I challenge that prevalent instinct and offer an alternative way of thinking about the scope and depth requirements of Help systems. The benefits of this approach are, I hope, better Help for users and, for our clients and employers, a more efficient use of technical communicators’ time. First, I’ll discuss three principles that underpin my perspective, then I’ll give some practical advice about writing Help that people will actually use.
Champion Advertisement
Continue Reading…
Three Underlying Principles for Help
My years as a technical instructor—often dealing with new products or technologies—have taught me that I did not need to be a lot smarter than my students. I’ve survived, more times than not, by merely staying a day ahead in the reading or a page ahead in the lesson plan. Ironically, as I got smarter about a topic, I sometimes found that the effectiveness of my teaching decreased, because I was missing the point that the students could grasp only so much in a given day. So, as I got smarter, my output exceeded my students’ input capacity. John Carroll, in his book The Nurnberg Funnel, talks about the Heisenberg uncertainty principle in training: The more complete training is, the less usable it will be; the more usable it is, the less complete it can be. I think this uncertainty principle aligns closely with my realization that instructional delivery systems must match up with a student’s intake bandwidth.
A more recent principle I find insightful is Wired magazine editor Chris Anderson’s concept of the long tail. His theory states that, although a significant number of sales occur around hits and best sellers, the majority of the market is distributed over smaller niches. Online stores can sell to such niche markets, because they do not have to maintain a physical inventory. Another principle relating to the long tail says that niche buyers derive great satisfaction from having their specific needs met—as this reaction illustrates, “Oh boy! A left-handed mustache mug with the Grateful Dead bear on it!” (Perhaps I reveal too much about myself with that example.)
A third principle that influences my approach to architecting Help systems derives from an observation I made over the course of watching hundreds of users during usability tests and in training rooms: Users go to Help only when they’re stuck and stay there only until they feel unstuck. In other words, users will not spend a lot of time reading Help. Instead, they return to action mode as soon as they know enough to take the next action. This is true for two reasons:
Reading text online is physically demanding.
Users would rather be working in an application than reading about it.
Implications for Help Architectures
How can you apply these principles to designing Help systems and developing Help content? Simply stated: Help needs to be a mile wide—it must cover everything—and 30 seconds deep—tackling only small amounts of detail at any given point.
The principle of the long tail tells us that we have to cover every topic—yes, even niche topics—in fact, especially the niche topics. Perhaps only five users might ever read a particular topic, but if that’s the topic they need and we get them there fast, their customer satisfaction level shoots through the roof.
Users often say they mostly use the Help for seldom-done tasks, not for their daily, routine tasks. So, in this regard , our usual instinct to provide complete scope of coverage is valid.
But how much should we write about such topics? My answer is: “About thirty seconds worth.” That’s all the time a user will be able to stand being stuck in an electronic document, away from his or her actual task. (I don’t know what the actual number of seconds is, but I know it’s short—and 30 seconds has a nice rhetorical impact.)
So, a challenge we face as Help architects and writers is figuring out what to spend our 30 seconds on. Don’t spend it telling a user that clicking a check box labeled Enabled will enable a feature—then noting in a result statement that a check mark will appear in the box, indicating that the feature is enabled. Instead, you might want to discuss the pros and cons of having the feature turned on or off. Tips, rules, examples, navigation (Where do I?), and interactions that are not obvious when first viewing a user interface—like dragging an object—are good candidates for a 30-second read.
The harder design question is: What do we do about the tough stuff that requires in-depth coverage or explanations? Two points:
Go into greater depth if you must, but get the 30-second stuff out of the way first. If you absolutely must cover the history of cardboard in your Help file, present that information in its own separate section that does not get in the way of more to-the-point user assistance. See my earlier UXmatters column, “Anatomy of a Help File,” for a discussion of task support clusters—a technique that can bring the 30-second read to the forefront, while still allowing access to deeper conceptual information if a user needs it.
Consider other channels of communication such as training, offline user’s guides, and even professional support services to cover advanced needs.
If the following statement describes your product strategy, you are in big trouble: “Our users will need to understand x, but our customer base is traditionally weak in x, so we must have an extensive section on x in the Help.” In this case, you need to do one or more of the following:
Simplify the product, so it does not require expertise in x.
Sell the product only to x experts.
Provide support for or consulting in x for a fee—or roll it into the price of the product.
Offer training in x.
Offer instructional interventions, such as e-learning, that develop the required x expertise.
What is a little disheartening is that most of these remedies fall outside the user assistance domain. In the case of the last solution, Help can certainly link to tutorials and other e-learning interventions, but it’s a risky assumption that a user will stop mid-task to take these interventions.
Help—What’s It Good For?
In truth, user assistance is not the most effective channel of communication for closing large gaps between user skills and knowledge and the demands of an application you’re documenting. So, dedicate the first 30 seconds of the Help user experience to users who know almost enough to complete the task without Help. Writers often overlook the following treatments when providing particular types of information, yet they fall easily within the 30-second sweet spot of Help:
parameters—Tell users a good initial value and what conditions would make it appropriate to increase or decrease that value. The following example gives a Help definition for a parameter called heartbeat: “[Product name] uses the heartbeat interval to tell the agent device how frequently to check in for information such as security policy changes. A heartbeat interval set at one hour is appropriate for most installations. If your environment is stable, you might consider setting the value higher—perhaps once or twice a day. If you are testing policy changes, you might want to temporarily set this value to as low as 10 minutes.”
check boxes—Provide criteria for selecting or deselecting a feature. Include costs or constraints for having an option on or off.
radio buttons and lists of options—Compare and contrast the options, if appropriate. Don’t just tell users how to select an option; help users make an informed decision.
text boxes—Tell users whether any rules apply—for example, if spaces are not allowed.
In deciding how much guidance to give users, make sure you understand whether a user interface device is asking a user to make a decision or merely asking for information about the user’s environment. For example, a pair of radio buttons that requires a user to select either POP3 or SMTP is not necessarily asking the user to decide what email client to use. It might be merely asking what the user already has. Depending on which scenario applies, the role of the user assistance will be very different.
Conclusion
We can’t save the world, and some of the remedies that might help users best are out of scope for the Help architect or writer. But what we can do is focus Help on what it does well—that is, provide a wide variety of 30-second informational solutions to get most users back on track and on task. In the end, the Help we create will be more usable, and the time we spend creating Help will be more productive—meaning we’ll spend it developing content users actually read.
In his role as User Experience Architect for IBM Security, Mike’s professional focus is on designing usable user interfaces that accommodate the user as learner. Previously, as User Assistance Architect at IBM, Mike identified tools, methods, and standards for integrating the content and delivery of user assistance, including documentation, Help, elearning, and training. He was formerly Lead UX Designer for CheckFree Corporation, where he instituted their User Experience Research and Design Center. Mike has a PhD in Instructional Technology from the University of Georgia and a Masters in Technical and Professional Communication from Southern Polytechnic State University. He is a Fellow with the Society for Technical Communication and a Certified Performance Technologist through the International Society for Performance Improvement. Read More
