As writers of technical content, we strive to help reduce the number of technical support calls. Yet, a recent post on the blog of LugIron Software refers to a quote stating that documentation can also increase the number of service requests.
Why?
Users feel overwhelmed
The first point in the quote states that overly comprehensive documentation scares users away. That may be true, but comprehensive simply means “of large scope” (Dictionary.com) and says nothing about the quality of the documentation, how it is organized, or how it is tuned for search.
If you deliver a voluminous, printed tome, users will most likely avoid it. If you deliver a help site without clear points of entry and orientation, users will probably look elsewhere. If your information is difficult to browse and search results are low to non-existent, users will give up.
You can improve the likelihood of user satisfaction by
- Performing a careful user and task analysis
- Single sourcing your content for modularity, reuse, and consistency
- Ensuring that your information provides maximum search returns
- Tailoring your information products to support roles and tasks.
For example, nearly all users can benefit from a simple Getting Started guide or tutorial. The guide can cover installation and configuration and then provide a basic orientation to your software. Emphasize what they can do with the software—not how cool the UI is. From there, give them branching options tailored to their roles and desired outcomes.
Users feel stimulated, but…
The second point in the quote bears repeating:
Documentation has so much cool stuff described, that it makes people’s imagination stimulated and they start thinking of other, even more exotic stuff they want to do but can not figure out and start a service request for it.
This statement is indicative of a damned-if-you-do, damned-if-you-don’t problem. I have to wonder how user assistance information has been presented and organized if it is perceived mainly as describing “cool stuff.” I also wonder how it’s structured. My earlier comments about organization, orientation, and findability apply in this case, too.
Regardless, the “cool stuff” aspect of software is a two-way street. If users want to improve the product or take it to another level, they need to provide feedback in the form of feature suggestions and enhancement requests. Product development teams cannot read their minds or restrain their imaginations.
Users feel enabled
Documentation that’s engaging should also make users feel that they have control. So how do you enable users without giving them too much?
You have created user profiles for your product, right? So why not ask “what type of user are you?” and give examples of typical users and associated tasks? Or ask “what would you like to do with Product X?” Then give readers some suggested branching points based on their roles and relevant tasks. Software and documentation need to be integrated in a way that provides a solution for getting things done.
Too often we waste a lot of words that over-emphasize the UI instead of including a separate UI reference section. If you find that you are constantly referring to the UI in ways that are not essential to performing tasks, then ask yourself whether the product design is truly effective or overly cumbersome. That may lead to a separate, challenging but necessary discussion for your product team.
Users feel involved
Our industry is buzzing about ways to get users more involved in contributing to product documentation by applying their product experience. Give them a voice and a stake in the process.
I completely support this approach. As a user, I rely heavily on active, peer-to-peer forums that not only share troubleshooting information but also “cool” tips. I understand how such forums can lessen user frustration and generate user excitement.
If you implement a process to enhance your documentation with user-generated content, don’t be surprised if the regular contributors comprise a small subset. Many users just want to use the product to get their tasks done. They don’t want to write the documentation. So even your participating users need to understand that the documentation must motivate, engage, and most importantly, provide answers for all users.
Even when user-generated content becomes part of your process, someone must manage it and ensure that it is accessible and usable. The most effective forums in which I participate have strong leadership.
Users feel bored
Regardless of what motivates or scares users away, I believe that our industry overlooks some of the obvious reasons why documentation often sucks. One factor that we ignore is the pervasive, stodgy writing style.
Companies should take a long, hard look at their style standards, or lack thereof. In this day and age of more casual conversation, why not integrate a more conversational tone into your documentation? As a long-time editor of tech docs, I have lobbied for a less formal tone for years, and I’m a lot older than many of my vibrant young peers.
Examples:
- We continue to write about how software “allows” or “lets” users accomplish a task instead of how it enables them. The only contexts for the word allows are access and security. And in a software context, I think that “lets” sounds ridiculous.
- We write “If you wish to…” before notes and tasks. We’re afraid to use the stronger and less formal want, or simply the infinitive form: To do x, click y. Wish connotes longing.
Read: “When you wish upon a star…”
I’d wager that while using our software, users are longing to finish work and go home. Do you ask friends or colleagues if they wish to go to lunch?
- We use may instead of the stronger, more enabling can. This usage sometimes creates confusion about whether we are giving permission or expressing that something might happen (as in maybe).
These examples are often defended as “polite” usage. I simply believe that they make our words far less engaging and even a bit dull. They create the impression that software is controlling users instead of putting them in the driver’s seat.
Of course, software documentation isn’t the only kind of technical writing. Making policies and procedures sound more informal isn’t easy. Writing about the installation and operation of heavily regulated equipment is a serious business where inaccuracies and mistakes can have serious consequences. But I still believe that even those types of writing can benefit from clear, plain language that sounds more natural.
I’m not advocating a departure from formal writing, but I believe that we are redefining our definition of what’s formal. I have often wished—that is, longed for—a change, and I welcome it.
But I digress. Plain language is a subject for another post.
Users feel content
The rise of social media brings new possibilities and new challenges that are making us rethink how we provide user assistance. Regardless of what we try and what we find effective, we need to remember that what we are delivering is user assistance. The bottom line is, users use our products, read our policies, install, configure, and operate our equipment for one purpose: to get things done.
So when you develop information for users, keep these things in mind:
- Give them a clear orientation so that they can decide where they want to go.
- Stop focusing on the “cool” factor of your product.
- Strive to increase the likelihood that they will find what they’re looking for.
- Consider their roles and provide tailored information.
I welcome your comments and hope that you will share your own solutions for creating a better user experience.
{ 1 trackback }
{ 5 comments… read them below or add one }
You’re responding to an interesting situation, one that I’m currently facing. Given that we adopt best practices for making the information findable, searchable, readable, etc., is it then okay to deliver a giant help file with all scenarios described and explained?
At the last Summit, I asked the Techsmith people why their help files were so sparse, yet their support forums dense. It seems like they skimped on some information that should have been included in the help file. Their response was that overloading the help file increased the cost of translation. Weighing the cost of translation doesn’t really make a big difference in how I write my documentation, but it is another dimension to the problem of how much documentation to deliver.
By the way, I like your site’s style. You’ve done a nice job making it very readable.
Tom, thanks for your comments, and thanks also for the compliment on my site.
I guess I have to answer your question with a question: How giant is “giant”? What I’m suggesting is a portal page that lists and describes various user roles and the typical tasks that each user performs. The role name could link to a subset of information targeted only to the selected role. This type of selection process may not work for you if the role groups in your organization aren’t significantly large. This was just on my mind because a few of my clients are managing this process using merged help files and including/excluding subsets with conditional text and other methods.
It’s interesting that you mention the TechSmith product help, because as I have learned my way around SnagIt 9, I have found the help a bit frustrating. But TechSmith does provide some great supplemental help through the forum, and I like their videos, too.
1. I think the “tone” or “style” of documentation’s verbiage is a lot less important than the number and organization of facts found in the content. The content’s explicit structure and visual cues must reinforce to the reader what kind of content is being presented.
2. The more robust (feature-rich) is the product, the more the documentation’s design and presentation should allow for an evolution of the user’s expertise in using the product. Of course, the product itself (interactive ones, anyway; an API ain’t going to adjust itself to the user’s expertise) should allow for this as well.
Paul, thank you for your contribution to this discussion. I agree that verbiage is secondary to the organization of the content. I only included it because (1) I’m habitually attuned to it; (2) I believe that we can improve it; and (3) I have worked with groups whose audiences often commented on the language factor. (I recall seeing the word “drudgery” in the comments.)
I really appreciate your second point. My ideal is an intuitive application with documentation that simply gives usage scenarios to take users to the next level. Thus the word “utopia” in the title.
Eddie, I think that the task of shepherding the user to greater expertise in using the product should be the *product’s* responsibility, not the documentation’s. The documentation has to do that job nowadays because today’s UI frameworks aren’t yet up to that task. If the product itself kept track of the user’s competence level and also knew more explicitly what the user is trying to accomplish, then supplying the user with the proper assistance for the task at hand would be a lot more feasible. But the UIs today aren’t designed to be intelligent about those kinds of things, maybe someday. So we TCers have user shepherding to do in the meantime.