Sticking with Obvious Information Versus Creating Information that Users Need

by Tom Johnson on Sep 4, 2013
categories: findability

In my recent tech comm poll about why users can't find information in help, one of the top answers was the following:

The answer isn't in the help because the help sticks only with obvious information.

No doubt at some point in your life, you've clicked a help file and browsed around only to find that the information is too basic and simple to answer any real troubleshooting questions you have have. Through repeated experiences like this, many people come to believe that help is generally useless.

For example, when I do WordPress consulting for websites, one of the most common problems is figuring out why the chmod settings for folders on web hosts don't take effect when applied via FTP. If WordPress can't write to a specific folder, it can't do things like update plugins or update the version of WordPress. Yet whenever I venture into help material for cPanel or Plesk or whatever platform these web hosts have, the question is rarely answered.

This is just one example where I fail to find the right answer because the help sticks only with obvious information. Each time I end up empty-handed in help, my confidence in clicking the help button in another system decreases.

Surely if people could just find the answer in help, no matter how deep it was buried, the experience of help wouldn't be a downward spiral. Is the problem that tech authors are sticking with obvious information and not covering the more advanced troubleshooting and power techniques that users want and need?

Categories of information

When we talk about missing information, it's easy to label the information as advanced or non-mainstream -- in contrast to novice or beginner type of information. But I'm not sure these labels are particularly helpful. We never write "advanced" information for the sake of writing advanced information. As we document a software program, we wouldn't seek out the dark corners of the app and complicated workarounds in the hope that more advanced users might find this information useful.

The question for the tech writer should usually be as follows: What questions or goals does my user have, and are those questions or goals answered in the help? In other words, it's a best practice to start with the user. What types of questions are users asking, what types of questions are coming into Support, what type of problems are users having, etc. That should be the focus -- not beginner versus advanced.

Real Scenario

Of course, it's much easier to state general principles than actual problems, so let me paint a more realistic picture. Creating help material gets tricky when you consider that your audience has a variety of skill levels. What is obvious to one person is not obvious to another.

For example, let's say you have two main types of users: developers and marketers. Both types of people use your software in different ways but with similar goals. For developers, there's an API that allows them to customize information in more advanced ways. For marketers, there's an interface that let's them grab code snippets to add information to pages.

It's easy to write for the marketing audience but much more challenging to write for the developer audience. How far into programming code can you go? Will documentation answer all the difficulties that developers are likely to encounter, not only interacting with the API, but in leveraging the API to create functional code and attractive output inside their web applications?

Usually API documentation does not explain fundamentals of JavaScript, PHP, HTML, CSS, or other programming languages. One assumes the audience is savvy enough to work in these languages, and hence does not need methods, functions, objects, and such explained. You do not have to write things like, "The JavaScript code block must be enclosed in script tags," or "The .push method adds the item as a new item in the last position in the array," or even that a convention like $("#myDiv").click is a jQuery event listener that triggers when a user clicks the element with this ID.

We skip over explanations of the basics and instead assume our audience knows all of this. But at some point, the help will tire out and fail to cover all the challenges developers will face. How do you render components dynamically on page load, integrating external libraries asynchronously? How do you create an infinite scrolling widget that loads quickly and contains a scroll bar with a size that adjusts gracefully as new information is added to the widget's data?

For this type of information, developers are on their own. As technical writers, we usually stick with the basic call patterns and methods supported by our API. But if we do this, do we shortchange our users who foray into help looking for more advanced answers?

The Flip Side: Not enough information

Now let's flip back to the marketers. Suppose your marketing users complain that the documentation for using the API is too confusing. A tech savvy marketer wants to customize his or her widget, and so has figured out how to call (sort of) the API to pull down the data he or she wants, but now faces a number of challenges. The marketer wonders, what are these references to dollar signs and hashtags ($(#myDiv)). Where does this JavaScript code go? And what is the whole .push command doing?

Is it your job to write documentation at a level an unskilled user can understand? Do you have to dumb down your developer-level instructions so that marketers can understand and follow them?

If marketers need a basic introduction to jQuery, JavaScript, CSS, and HTML, they're clearly a long way from understanding and leveraging your API for any development. If this is the case, it's unlikely they'll find the help useful. You could explain all the code, but then you would be left with a novel of information instead of the more succinct code instructions that developers prefer.

These are the challenges with documentation. Users are invariably at many different technical levels, and it's impossible to fully know and write for them all in a way that meets every user's need. This is why it's imperative that technical material allow users to skim and skip around, so they can go to the information they need and skip over the material they already understand.

The variety of skills levels among users is why technical writing differs so significantly from literary writing. In literary writing, we expect that users/readers are usually on the same level of awareness, and won't be skipping around. Not so with technical information. With technical information, a user might read just one sentence on an entire page, while another user reads the entire page and follows every link.

Real reasons why advanced information is absent

Fortunately, by including subheadings, links, search, table of contents, etc., you can allow users to go right to the information they need (if it exists). The beginning users can read the introductory conceptual material while the advanced user can search for a particular error messages and resolution. The problem isn't so much one of organization, because if the answer is in the help, search will often find it.

Most likely the real reason more advanced information is absent from technical material is that it's much harder to come by. A topic might take an entire day to figure out, after testing and asking various engineers questions. After all of your investigation, you might have just one little note or paragraph. If you spend 10 hours finding one answer, your to-do list piles up and you might have trouble meeting deadlines. No one has infinite bandwidth to create endless documentation that meets users' needs at every level.

Another reason the advanced information might be absent is because the information is beyond our own skill level to document. This is especially true with API documentation. When you write for programmers, you have to develop a knowledge of programming to provide insight at the level that users might need. That's tough stuff. For example, coming back to the widget with infinite scrolling, I might be able to tap into a jQuery plugin to make that happen, but I'm light years away from "rolling my own," as they say.

Another reason help sticks with obvious information is because we may not be equipped to find it. We may be documenting something that we don't have access to. Consider the challenge of documenting a storage network array, or some technical product that you don't have direct access to. In many cases, you'll have to rely on engineers for information, and if this is the case, you're at the engineers' mercy to define the information needs of the user.

Another reason help is silent on more advanced topics might be the division between decision support and technical support. If the information users seek includes strategies on how to use the product in a particular business scenario for maximum impact, it's unlikely that help is going to address those needs.

For example, my company's product involves gamification, and there's a lot to know about what techniques work in different situations for different industries and goals. It's currently beyond my role to recommend implementation strategies. For that we have specialists who looks at the user's business environment, goals, and match up techniques that will work best.

Conclusion

I hope I was able to shed some light about why help sometimes sticks with obvious information. Getting the right information into the help material is not an easy problem to solve. It is perhaps the problem to solve in creating help material, as the type of information we write depends on the alignment of so many factors -- input from other groups, demands from product managers, legacy expectations, our own sense of information needs, the variety of skill levels among users, and more.

How have you been able to gauge your audience's information needs to go beyond obvious information? If you lean towards more advanced instruction, how do you avoid alienating your lower-skilled users?