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

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.

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • Tricia

    Great post, Tom! I myself spend a lot of time brainstorming the all of the possible scenarios for that “FAQ” section. The dilemma I run into stems from the fact that our tools are currently under a lot of R&D testing by customers, and therefore we are required to cater very closely to their needs. Sometimes our IT department is even asked to manually register them for the tool when they skip a step (and fail to read the quick start!) in order to make their experience as easy as possible. I feel that this sets a bad precedent and doesn’t allow me to successfully execute an adaptive documentation model that ultimately helps the user.

    • http://idratherbewriting.com Tom Johnson

      Tricia, if your tools are under research and development, they’re probably prone to a lot of change, right? If so, how do you write documentation for a constantly changing app?

      I’m not really sure I understand what you mean by “manually register them for the tool when they skip a step.” Must be an internal process of some kind.

  • http://idratherbewriting.com Tom Johnson

    I mentioned in a tweet a sense of an upcoming law/paradox. Here is it:

    The more information you add to a help file, the more answers it provides. At the same time, the more information you add, the less findable the answers are, so the less answers the help provides.

  • http://www.sdicorp.com/Resources/Blog/articleType/AuthorView/authorID/24/lkunz.aspx Larry Kunz

    Tom, this is great, and it couldn’t be more timely. I appreciate your writing it all down and sharing it with us.

    What you’re describing, of course, is a rudimentary form of collaborative or community-based documentation. You began by putting everything into the help that you thought the users would need. (I actually agree with Alistair Christie that you needn’t have included everything.) Then, as users identify additional information they need, you’re adding it to the help.

    Unfortunately, right now this is labor intensive for you. And if the call volume increases you’ll find that you’re actually a bottleneck: you won’t be able to update the help fast enough to keep up with the users’ requests.

    As community-based documentation really takes off, I envision users’ requests going into forums (or something similar), and the answers being posted to the same forums — either by you or by other users. If the user community really becomes active, your role evolves into more of a curator (editing user-generated content and tagging it for findability) and less of a content producer.

    The way out of your dilemma will be to channel the new content into formats that lend themselves to findability — such as forums and FAQ lists — rather than putting everything into the help. As a profession, we’re still learning the best practices for doing that.

    Sorry for the long-winded response. But you’ve really piqued my interest here. Thanks again for a great article.

    • Kay Robart

      Sorry I’m posting this so late, but I just discovered this site.

      This topic poses a dilemma for me as a user that I’m not always sure I’m answering as a writer. As a relatively experienced user of software, I only look for help if I can’t remember how to do something or if I am having a problem. It is interesting that Tom just had a revelation that answers aren’t always in the help, because that is almost always my experience in this situation!

      And I HATE knowledge bases and forums, as you are recommending, Larry, because I can never find anything using them. I do a broad search and get a couple of thousand entries. Who can sort through all that? I do a narrower search and get nothing. This is why I absolutely hate the direction Microsoft has gone with its help, because I usually just want to see the help files, not all the articles and related documents on the knowledge base. If the answer is in the help files. And I have only occasionally gotten useful responses from users on a forum. I don’t think I’m trying to do anything that unusual, either.

  • http://www.sdicorp.com Julio Vazquez

    Good stuff, Tom. I have an approach to help that may be of interest (or not). I’ve done this a number of times and it may minimize the missing information (thought I doubt it totally relieves it).

    Start with the user tasks (basic strategy, right?) and document those first. Explains the steps to achieve a single goal in the product and note the information required to complete the task successfully. Note the complex panels and target them for detailed explanation.

    After writing the tasks – write the information that describes the complex interfaces and generalize what is needed in these panels. Give enough background to make the panels make sense.

    Write explanations for all input areas on all the interfaces. Include the allowable values for entry fields and how information in one field effects other fields, if necessary.

    Link the tasks to the information about the panels and the fields. This makes the information available at point of use, if the help is accessible from the interfaces. This allows soemohe who’s unsure the ability to get the information and the more experienced to just do what they do.

    I know; all this is basic, but I had to just spout it out. Have fun with the helps!

  • Kathy Wellisch

    Although my focus isn’t in community-based documentation, I tend to use Larry’s solution and create supplementary sources.
    One of the questions I find myself asking SMEs far too often is, “How often will people use this?” Where the information is related to bugs, special situations, etc., it’s far easier to create a note in the Help and say, “Find out how to do/solve this from ___ paper on our web site.” In this way, the Help stays organized and the information is at least referenced in a logical, easy-access location.
    Of course, supplementary docs always lead to the question “What gets left in the Help?” I find my decisions are based on 1) length of the explanation, 2) how frequently the information will be needed. And then, of course, I can’t go creating too many supplementary docs or I run into all-new organizational problems, helping people find the right doc on our web site. (I don’t get to be the boss of the web site.)
    Interesting series. Thanks.

  • http://www.itauthor.com Alistair Christie


    This is a really though-provoking post – thanks. The part that really interests me is how dealing with support calls from people who are actually using the software has shaped your approach to creating user assistance. That’s how it *should* work. My own experience, documenting enterprise-level software, is that the tech writers and the end users often never come into contact. The end users (yes, I know, horrible expression, but you know what I mean) contact their internal support people and, if they can’t help, their support people log a support call with our third-party call centre and it then gets picked up by our support people who generally manage to solve the issue very quickly and without reference to anyone else. The tech writers usually never find out about these support calls unless they take the time to check the support system regularly, or they hang out with the support guys (which tends not to happen just because we’re in a different part of the building). So it’s not unusual for tech writers to work on a product for months, or years, and never talk to an end user. And it just stands to reason that if you had a direct line to your end users your documentation would inevitably be much more fit for purpose, and would get better over time.

    Maybe working periodically in support is something all tech writers should do.

    But as for your question: more information, good or bad? I don’t have an answer. However, I really believe that tech writers have to get away from the habit of just bashing on and documenting stuff. Time and time again I’ve seen tech writers succumb to the temptation to just document whatever they see in the user interface. This is always going to result in pointlessly bloated documentation. It’s the scatter-gun approach: “How should I know what users will want to know about? So I’m just going to document as much as possible.” It seems to me that Julio’s comment – “Write explanations for all input areas on all the interfaces” – exemplifies this approach.

    I’m convinced the result is that a lot of time is wasted documenting things that, in a well designed interface, are obvious to the user. Those things tend to be the things users do most of the time: the basic, nuts and bolts operations that were in the original design of the application. The interface makes it easy to figure out how to do those things, so users don’t need help with that. It tends to be the secondary things – the stuff that got added to the application in later iterations, and which are accessed via a menu item rather than being immediately obvious – it’s those things that users tend to need some help with. But generally, to make the initial help system at least adequate for release, the tech writer needs to do a lot of thinking up front, ask a lot of questions, and get a pretty good understanding of the workflow through the application, and what tasks different sorts of users are trying to complete, and a fairly clear picture of how the application will really be used in day-to-day practice, before he or she starts writing help topics.

    After the initial, good-enough-for-release version of the help, it would be nice to think that, with the assistance of users the user assistance gets better and better over time. In practice I think this is still all too often an aspiration rather than a reality.

    I really like Larry’s take on this: “If the user community really becomes active, your role evolves into more of a curator … and less of a content producer.”

    Is this yet another alternative title for our role: information curator?

  • Pingback: What online help needs is really good search results()

  • Steven

    Tom, I am not a technical writer, but I’m interested in the subject and I have been following your blog for a few months. When you started writing about help systems, it reminded me of the trouble I had when I switched to Microsoft Word. I needed to write in Spanish, which requires accented characters. The help was almost useless; I was looking for “accents” and “foreign” and a few other keywords. Finally I stumbled across “international”.

    Their method for obtaining such characters wasn’t bad, but it certainly wasn’t intuitive and the help system didn’t help.

    In addition, there was an even better system available — the “US International” keyboard layout. Built into Windows, but the first explanation I ever saw was on a package for a related product (Spanish proofing tools). It was not described in Windows 95 or anywhere in the Office suite.

    My thought was, Microsoft evidently relies on a small group of people who all think alike to create their Help systems.

  • http://www.bluemangolearning.com/blog Greg DeVore

    Great post and great response by Alistair. Over the last year or so we have taken basically the approach that Alistair describes, but even to a bit more of an extreme. We only document questions that users actually have (actually we seed it with 10-20 questions that we know they will probably have). We only add new content as real questions come in. It has two effects:

    1. Our help doesn’t get bloated with useless or obvious information.
    2. We never have to work on a documentation “project”. We just do it a little at a time as is necessary.

    We also take the approach that Tom describes of never answering questions without adding to the documentation. It takes a little bit of discipline but provides big benefits.

    To do this, you have to have a system that lets you reorganize things easily as your help grows. But the organization isn’t as important as you might think. If you have good search in your help docs then people will be able to find what they need without too much hassle.

  • http://kwritenow.com Kristi

    Without knowing which of the users will use what, one could spend all of one’s time documenting the basic tasks and changes to those tasks for each release of a complex project, not leaving any time for document improvements. The help system could grow and grow without becoming more searchable, or sophisticated, or well-labeled.

    If writers in a department are supporting multiple complex projects, the best way to get everything “done” can be to do the bare minimum of getting a change documented, without ever improving the contextual information about how the features interact with each other.

    If a company has many products, clients, configurations, user types, etc., it’s a large task to keep straight who needs what information. But perhaps some of those user types are just not going to use the help system. They’re going to call their IT people, or their questions are rare and specific enough that they will use a knowledge base or user list. Or, conversely, maybe they are the only people who will use help, and so we should scrap the basic tasks and go right to the complex topics.

    It can be tough to justify stopping the merry-go-round of deliverables in order to survey the passengers, per se, but at least after that, one could stop writing for those who aren’t riding.

    When I use a help system, I don’t expect all the answers to be there. I know I might have to venture to the forums or call support. I do, however, expect to be able to quickly determine whether the information in the help system or not. With a wide, shallow help system that has good labeling, I can do that. I can open one or two books and be satisfied that I’m finished looking.

    That’s less likely to happen to me, though, if the writers are well versed in what users like me are looking for. It’s time-consuming to gather that information, but it saves effort and money in the long run.

  • Jennifer

    I guess the biggest problem I have encountered with finding info in Help is simply one of terminology. Often writers will rigidly stick to the terminology of the tool and not consider wider naming possibilities that users could be using, particularly if they also use other tools, each potentially with their own terminology.

    As Steven above pointed out in his entry on finding info on using accents in Word, how many times does a user get stuck at the start simply trying to figure out, “What’s my problem called??”

  • Chris Martin

    “Help” doesn’t have to be “the help file/system”, you know. We tend to forget that. A well-designed error message–here’s what just happened, here’s what you might want to do to make this message go away–goes a long way. People want helpful error messages. I know, getting to work on messaging isn’t always possible or practical, but it should be.

    For example, here’s one I got this morning: ARERR [8703] Bad attachment size

    What that really means is, you can’t attach anything larger than 2 MBs. And you can only attach certain kinds of files. I’d like to be told that here because (embarassing as this is to admit), I really don’t want to go poke around in the help file. Just tell me what’s up so I can keep going, please.

  • Patrick Warren

    @ Chris Martin +1
    “Help” doesn’t have to be “the help file/system”

    Totally agree and this is how one of the groups I worked with recently approached in-house application development, and how I’ve been setting up open-source CMS’ too. This is that ‘point-of-need-learning’ or information need I think I may have mentioned previously.

    I also don’t consider it embarrassing at all to ask for it this way and not have to poke around in a help file. Today’s knowledge workers are busy as ever, tasked with being as productive as possible (it’s a global market place now folks; more competition). Having to run a series of tasks and actions just to get that little bit of information is wasted effort and inefficient; unable to effect or achieve the desired result with reasonable economy of means.

  • Dan

    I love this post.

    It’s actually something I’ve been struggling with for a while. I typically prefer to follow a more minimal style; ask if something is essential or not and cut any topics that aren’t 100% essential. But lately, I’ve been really questioning this. It should be as simple as, “Does a user have a question about it?” If you ever get the question, you should answer it.

    People often get aggravated when they see a 400 page manual; but if it’s well indexed, they’re going to be happy that it’s comprehensive. I guess, if findability is an issue, leaving things out probably isn’t the answer.

    Anyway, thanks for the post. Definitely digging it.


  • http://www.imaginaryplanet.net/weblogs/idiotprogrammer Robert Nagle

    First, great long article. Really one of the best things I’ve found on the web. Ironically I read it while putting off having to write a book chapter about CMS navigation.

    A few random thoughts about the series:

    – WordPress 3x now will offer more menu control, which should improve navigation considerably.
    – one reason Google sucks for finding technical answers is that Google is a commercial enterprise and can easily be gamed.
    – facets are interesting, but they are dependent on your help platform. Also they are useful mainly if the users are performing different functions.
    – ebooks are an interesting hybrid medium (and one I’m working on right now). Lots of alternate navigation/browsing methods plus better use of hyperlinks.
    – agree that mediawiki’s templates make it easier to organize content. But if they are autogenerated (and not watched over by a human editor), they become useless.
    –thanks for reminding me that wp search results are in chronological order!
    — I think your problem in the first or second part about shallow help pages is a result of a schema like DITA which tends to segment things too narrowly.
    — it helps to know how your audience looks for information. A lot of It staff (my target audience) will use search before anything.
    — the big problem is that people never know what to search for. All they know is how to describe their problem. I think a glossary can help with that.
    – I’m a wordy/prose-oriented person. It was a shock to me when people found it hard to find information in my dense prose. Labels are important — maybe the most important thing…
    –that said, for conceptual things, people like content which is a readable chapter.
    –hypertextuality has a down side, especially if you need to remove a subset of the docs (for a quick start or something like that).

    Alistair — I agree about the problem of documenting things which are obvious to the user. I’ve written elsewhere that screen shots are unnecessary if the GUI is well-designed and should only be used in special circumstances.

  • http://gryphonmountain.net Ben M

    Tom, interesting approach re: writing help before answering users’ questions. I agree that pointing people to the docs whenever possible may open their eyes to its helpfulness. A tricky part about your approach is if a review process is needed before the writer can publish the help update, that delays the response to the user. That’s where a community approach like Larry suggested may alleviate the problem because at least the answer is out there before it can officially get incorporated into the docs (if you go that direction).

  • Pingback: July Technical Linkdump | Idiotprogrammer()

  • http://www.wouldyouratherquiz.com Steph – Woud You Rather

    It’s actually something I’ve been struggling with for a while. I typically prefer to follow a more minimal style; ask if something is essential or not and cut any topics that aren’t 100% essential. But lately, I’ve been really questioning this. It should be as simple as, “Does a user have a question about it?” If you ever get the question, you should answer it.

    People often get aggravated when they see a 400 page manual; but if it’s well indexed, they’re going to be happy that it’s comprehensive. I guess, if findability is an issue, leaving things out probably isn’t the answer.

  • Pingback: Customizing the “No Results Found” Page with Helpful Wayfinding Tips | I'd Rather Be Writing()