Search results

Faulty Assumptions About the Scope of Help Content? [Organizing Content 15]

Series: Findability / organizing content

by Tom Johnson on Jun 11, 2010
categories: findability technical-writing

I've written more than a dozen posts in this series on organizing content. Until now, I've been working under the assumption that if the help content were just organized well, if it were findable by the user, in an intuitive, accessible way, then it would solve much of the problems of help. I've been assuming that the problem is one of findability and organization. The help content is there, but it's so buried, so impossible to navigate to, so dang hard to find that it ends up being useless.

But today I had an experience that made me rethink this assumption. Maybe the problem isn't so much that users can't find the right help topic for their situation. It's that the topic they need isn't in the help. It's not that the topic isn't findable. The topic isn't there at all.

Ever since the release of Swordfish (my fake project name), I've been filling a support role for the application as well. It's a small group, and I wear multiple hats. I know that this support role, while annoying at times, is also advantageous because it gives me an insight into the real problems users are having. Through this close connection and user-informed perspective, my help can provide real answers that users want.

But in reality, the phone calls keep coming and coming and coming. Since the release of Swordfish, I must have responded to about 50 different users, with some users asking multiple questions. A few users have me on speed dial. I see their phone numbers flash on my phone and I think, oh, it's Frank again.

Why is it that all of these users don't t turn to the help material to find answers to their questions?

As I started listing their questions and assessing the help, it dawned on me: the help did not contain answers to these questions. Their questions involved bugs and quirks in the application, edge cases, seemingly random scenarios, unexpected situations, abnormal uses. Few people ever called me to ask a basic question.

Here are a few fictional examples. Joey tries to upload a file and gets an illegal upload error. It turns out he has a space before the period in the file extension that causes the error. Another user finds the system times out randomly and doesn't save the typed information. Another user wants to do something that isn't possible to do in the system. At least 75 percent of the questions don't involve matters of basic user education, but are rather related to bugs, special situations, or other types of information not typically located in help material.

No matter how many navigational aids and facets and search keywords I add to the help, if the help doesn't include the answers people need, it won't be helpful, right? It won't matter how findable and well-organized the content is if the content users need isn't there.

A More Fundamental Issue

This led me to think about a more fundamental issue than organization or findability: the type of content itself in the help material. What degree of user problems and questions should help address? All of them? Most of them? Some of them?

In a podcast Alistair Christie recorded last year, he mentioned that you don't have to document everything. Less is more. But is it? As a user, would you rather have a massive help file that contained answers to almost every question, problem, and scenario (if you could just find it), or would you rather have an abbreviated help file that only covered the most common tasks in an easy-to-navigate way?

While I agree that in many situations "less is more," this truism doesn't help me answer support questions. It continues to render the help as a resource that is pushed aside because it doesn't help the user.

A New Goal for Help

To address these concerns, I have a new goal I'm trying out. Before responding to user questions, I make sure the answer is in the help. It may take me two hours to research and type up a new topic and republish the help system before I respond to the user, but it's better that way. When I respond, I send a link to the specific topic in the help file. This teaches users that help is actually a thorough information resource with answers to their questions.

Ever-increasing Help Content

With this method of documenting everything, after some time the help material will grow and grow. What started out as a 197 page manual may well grow to 300 or 400 pages. The more topics I add to the help, the more potentially informative it becomes.

But another problem also develops: in a thoroughly massive help file, it becomes more difficult to find information. If a user expands a TOC to find dozens of subfolders and sub-subfolders and scores of topics within each subfolder, the system of navigation will become intimidating and cumbersome. The user will revert to keyword searches as a primary means of finding searches. After a few fruitless keyword searches without the right results, he or she may simply give up. The easy-to-use navigation system suffocates under the load of help topics.

Assertions to Explore Further

I've made a couple of conflicting assertions in this post that need to be explored with more research:

  • Assertion #1: More information in the help file will allow the help material to answer more user questions. In turn the help will become more useful.
  • Assertion #2: More information in the help file will make it difficult to locate the right topic, since the topic will buried in a mass of other topics. This lack of findability will make the help less useful.

Your thoughts?

Update: Check out Alistair Christie's post, What online help needs is really good search results, for an extended discussion of this topic.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.