Organizing Help Content: Breaking Out of Topic-Based Hierarchies

My upcoming presentation at the STC SummitAt the upcoming STC Summit in Sacramento, I’m presenting a session titled Organizing Help Content: Breaking Out of Topic-Based Hierarchies. The title is a bit wordy. It’s basically information architecture applied to help content. Or even simpler, making help content findable. In this post, I’ll give you a sneak peak at what this presentation is all about.

One of the biggest challenges technical writers face is enabling users to find the right help topic amid hundreds of topics in a help system. Although the default approach in an online help file is to group the topics by task or topic in a table of contents (TOC), this method has its shortcomings. The traditional TOC only works well if each topic neatly fits into its own group, and if users are familiar with all the terminology.

In reality, topics frequently overlap with each other and can be grouped in myriad ways depending on the perspective. The terms used to describe the topics are also often unfamiliar to users. As a result, when users open the help to find information, they see an intimidating array of topics to look through, with names that don’t mean much.

In many cases, the problem isn’t a lack of information, but that users can’t find the information. How many times has a technical writer grumbled “read the manual” when a user asks a seemingly simple question. How do you make your help content more findable for users? How do you enable the user to find the exact topic he or she is looking for with little effort? That’s the main question I address in this presentation.

Alternative Organization Schemes

Of course you want to implement an organization scheme that will be most familiar to your users. But any group of users will have a wide variety of perspectives, backgrounds, experiences, needs, schemas, skill levels, locations, and learning preferences. How do you help all these different users find a specific topic in a sea of help content?

There are a variety of ways to organize help content. The traditional topic-based organization may not always be the best way.

There are a variety of ways to organize help content. The traditional topic-based organization may not always be the best method.

Fortunately this problem isn’t unique or new. An entire discipline, information architecture, is focused on solving the problem of findability. Information architecture’s goal is to improve the user’s ability to find information in a complex system, whether that system is a website, blog, library, grocery store, or something else with a lot of items.

The organization scheme you choose should be one that makes sense not only for your users, but also for your product. Some products, such as shoes, naturally give rise to certain facets that you could use to organize the information (for example, mens/womens, sports, dress, kids, running, basketball, tennis, color, size, and so on).

With help systems, because the product is information, the facets aren’t always so apparent. But there are still plenty of organization schemes to draw upon. The following are fifteen organization schemes you could use as alternatives or supplements to the topic-based TOC.

Organizing by audience. Audience may be identified by their role, discipline, or department. The idea is the same: by identifying the audience, you can present the topics most relevant to that audience.

Organizing by skill level. Skill level can be divided into beginning and advanced tasks. Users new to the system can see a list of topics appropriate to beginners, while advanced users can see the more difficult topics.

Organizing by format. Format can be grouped by videos, quick references, manuals, online help, diagrams, tables, or other formats. This helps users looking for help material based on their learning preferences.

Organizing by popularity. Popularity can be established by most emailed, most blogged, most viewed, or most searched content. Users know that if a topic is popular for others, it’s probably relevant to their needs too.

Organizing by story. Stories might include persona-driven workflows described for various roles. In the stories, as you describe the actions the users take throughout the workflow or process, you can link to the tasks or topics that describe those actions. This story-driven structure can give users the big picture while providing navigation to each of the specific topics for more detail.

Organizing by chronology. A chronological organization might present topics linearly based on the workflow sequence users step through as they use the application. Alternatively, chronology-based organization could include information based on release date, or it could show the latest topics added to the help.

Organizing by problems/issues. Problems/issues could include frequent support requests or knowledge base articles. This problem/issue-based organization might contain titles highlighting broken functionality, bugs, or non-existent-but-frequently-asked-for features. Highlighting problems is the reverse of traditional documentation: rather than explaining the features, you’re calling out areas of broken/non-existent functionality.

Organizing by alphabetical order. Alphabetical ordering is usually an index, which is more commonly omitted in online help in favor of search. However, indexes can also provide users with a way of learning the official terms used in the help. Once they know the right terms, users can quickly move to the place in the help that provides those terms. Users are usually familiar with referring to indexes as a way to find content.

Organizing by screen. Screen-based organization schemes are usually not a best practice as the default, but depending on the application, this organization might help users stuck on a particular screen. In this system of organization, you list out all the tasks and topics that relate to each main screen. If you already have context-sensitive help, you probably already have screen-based topics.

Organizing by geographic location. Location refers to the geographical context of where the user is located. If some information might be specific to users in, for example, Africa, Japan, or South America (such as time zone notes, terminology, translated material, etc.), this organization scheme can help them locate what they need. Remember that usage of an application often varies based on one’s location. For example, the European Union has specific data privacy laws that might affect what information you can show in your application.

Organizing information in-context. In-context organization groups the help topic in the location where the user needs it. This is often referred to as context-sensitive help or on-screen help. Help icons in the interface, pop-up modals when a user opens a new screen, or embedded on-screen text can help users find information when they need it.

Organizing by related information. Related information contains a series of logically related links placed at the end or along the side of each topic. This method provides navigation directly within the topic, where users often spend the most time. To reduce cross-reference errors, related links might be grouped in relationship tables.

Organizing by next steps. Next steps is similar to related information, except that the next steps are more sequential and appear directly below the last paragraph of the topic. In a modular authoring, because each task is chunked from other tasks, many individual tasks may build on each other but be discrete topics. If each task is chunked as a discrete topic, search results may spread them out in a disconnected way. The next-steps link below each topic gives coherence to these discrete-but-connected topics.

Organizing by business goal. Many times users have general business goals in using an application. These goals don’t often translate into task or topic titles. For example, a user may want to do work in less time, or increase focus in meetings, or encourage communication among employees. Understanding your user’s goals is key to writing help in the first place, but we often forget these larger goals and get mired in more technical specifics. When you organize by goal, you can connect the larger business goals of the user to specific how-to tasks.

Organizing by level. Content can be divided into a series of learning levels, similar to the way video games or karate lessons move users from one level to the next, providing more advanced information as the levels increase. This organization scheme is more of a course-based organization pattern.

Many of these organization schemes can be leveraged by perhaps tagging the topic or assigning it to a specific category, and then calling all of those tags or categories. Additionally, these techniques can be layered on top of each other or used in various combinations.


Invariably in discussing findability, many writers believe search will bail out the user when the TOC fails. Search does work well for known items – meaning, when the user knows the exact term he or she is looking for. But we often make erroneous assumptions about how search works in help systems simply because of our familiarity with Google.

Search algorithms. Google’s search works primarily through a system called Pagerank, where backlinks pointing to a site act as a vote of confidence for that site. The more votes, the higher the Pagerank. The pages with the highest Pagerank rise to the top of the search results.

Your help system probably doesn’t use Pagerank at all to determine search engine results and visibility. Every help authoring tool has its own search algorithm. For example, Flare ranks exact keyword matches highest, then keyword frequency, and then keyword location. WordPress gives more weight to more recently authored content. SharePoint has another system of rank for showing content.

You need to understand the search algorithm that is driving your search results. Once you understand your search algorithm, you can take appropriate steps to increase visibility of help topics in searches.

Terminology challenges. One major problem in optimizing for the right keywords is figuring out which keywords to use in the first place. Users may employ a variety of terms to refer to the same thing. Do you go with the official term the project team uses, or the term more familiar among users?

Some help authoring tools provide synonym features, in which you can equate the same term to provide similar results. Still, helping users locate topics when they don’t know the right terms is a major limitation of search. This is why organization schemes (which allow browsing) are still important.

Multiple algorithms. Another consideration is how to optimize your content when it is searchable within a larger infrastructure than just your help system. You may use a help authoring tool to create your content, but then store this content on a SharePoint infrastructure, or push it out to a website indexed by Google. In that case, users may use another search tool to find your help material. As a result, you have to optimize your site for two different search algorithms – the help’s search and the host’s search.

This can be tricky, because if you stacked a keyword with a lot of frequency in your help topic, optimizing for Flare, Google may penalize you for trying to game the system with overuse of this keyword. Google prefers that you repeat the keyword only about once every 100 words. Flare, on the other hand, won’t penalize you at all for repeating the same word 50 times.

Video and images. If you have video and image content, you need to take extra steps to ensure they appear in the search engine results. With video, about the only technique for ensuring search engine visibility (beyond the title) is to include a transcript below the video. You can also create video XML sitemaps to increase visibility on Google. With images, a lengthy caption can provide the text search engines need to read the content.

Intelligent search results. Ideally, you want the most popular help topics to gravitate higher in the search results, given that more people are looking for them. If you can weight your help topics with metadata other than keywords within the topic, this can improve your search results considerably.


Both browsing and searching are two fundamental ways users can locate the help topics they need. In this presentation, we’ll dive deeply into these two subjects with examples, challenging scenarios, and practical advice.

Adobe RobohelpMadcap Flare

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.

  • Kathy Sierra

    Excellent start. The only category I do not see here is to organize by “emotional state of the user”, though one can infer it by using context and problem organization. Perhaps the single biggest downfall in most help systems, in my opinion, is that they do not match what the user is going through at the moment of consulting help. Or as I have said in my talks on this, there is a gap between what the help creator thinks the user feel and what the user actually feels.

    At the moment of needing help, the user is NOT simply “intellectually curious” about the topic, yet that is how most help systems appear to have been designed. The needs of someone who is currently frustrated, bordering on angry, and blocked from what they are trying to do… are radically different from someone who just wants to “know” stuff. The difference between verbs and nouns.

    This approach can and should impact everything from the choice of categories to the context in which they are offered. And the tone of the copy matters too. The more we reflect the user’s likely feelings the way a human would, the better chance we have of providing help in a meaningful and useful way to the user.

    I realize I am preaching to the choir here :). Thanks for giving me a place to do it.

    • Tom Johnson

      Kathy, thanks for your comment. I agree that writers should account for the emotional state of their audience. I remember listening to a talk from you several years ago on this topic, and I wrote about it here. However, I’m not entirely sure how this would play out in an organization scheme. How could you divide up content like this? Red Hot Angry | Frustrated | Confused | Curious | Inquisitive?

      As a general trend, minimalism is intended to address user frustration. Minimalistic authoring encourages authors to write as little as possible to allow the user to quickly get in to the help information and then get out. But I tend to think minimalism only increases frustration. My approach to improving help material is to infuse topics with various learning styles, incorporating illustrations, video, and action in addition to text.

    • Aaron Fulkerson


      You’re awesome. Much of our success at MindTouch, especially early on, was driven in large part by you inspiring me back in 2006. Thanks! I still quote you often. Please take a look at what we’re up to at MindTouch these days. We offer a social knowledge base and build enterprise help communities for some of the world’s largest technology and media brands.

      • Tom Johnson

        I found Kathy’s blog and talks inspiring as well. I always hoped she would return to blogging, but I don’t think she ever did.

        • Aaron Fulkerson

          To my knowledge she hasn’t. Bummed. I also missed her at the last ETECH workshop she had to cancel, which to my knowledge was cancelled for the same reasons she stopped blogging. I had attended two of her workshops in 2006 and 2007 though. She’s kick ass.

  • Jonatan Lundin

    Hi Tom,
    You need some kind of classification mechanism to be able to classify topics into the various organizing schemes. DITA 1.2 is introducing such a mechanism called the Subject scheme map.

    It is a very interesting feature. First you declare subjects in a subject scheme map. Subjects could then be for example audiences, skill levels, etc. Then you classify your topics to one or several subjects. A facet broswer allows you to select whatever subject and the topic result list is dynamically filtered to only show the topics that are classified to the selected subject.

    I haven’t come across an information viewer that supports the DITA subject scheme out-of-the-box, but I hope that such a information viewer will be available soon. Maybe someone else knows about such a browser?

    • Tom Johnson

      Jonatan, that new faceted classification feature in DITA 1.2 sounds fascinating. I think it’s definitely going to improve the usability of the DITA outputs, which have been criticized for their primitive characteristics. I’m interested to see this in action. Do you know when 1.2 is projected to be released?

      • Jonatan Lundin

        As Larry Kunz mentioned is some reply recently, DITA 1.2 is approved. The subject scheme (which uses the new key construct) will bring a lot of new possibilities for building viewing environments to increase content findability.

        Also, the subject scheme will also be a help to improve release management. And at the moment I’m looking into how the subject scheme can be used to improve conditionalizing of content. A subject scheme map is a simple taxonomy that can be used setting conditions, but DITA still has some issues I would like to see changed.

        A subject scheme map can be used to declare the metadata enumerations you need for your content. Previously in DITA, all the enumerations where hardcoded into the DTD (for example the values for the audience attribute). But now in DITA 1.2 you can declare your own controlled vocabulary.

        • Tom Johnson

          Cool, I’m glad to see that you’re knowledgeable about the specification and can speak to its usefulness. I’d love to see an example of the implementation. Do you have any DITA 1.2 example implementations?

  • Aaron Fulkerson

    I touch briefly on how we’re organizing for some of our customers (like Autodesk) in order of Products > Language > Product Version in the recent presentation I gave at WorldWare. You can find it on Slideshare here:

    I also covered the following topics:

    Topics covered:
    * The impact of “social” on product help
    * Social Customer Relationship Management (SCRM) and how product help can provide a valuable foundation for SCRM
    * Help, Marketing, and Sales personalization
    * Socializing translation and localization
    * Effective information architecture for product help communities
    * 3 Guiding Principles of effective (social) product help
    * 5 Community Rules of Engagement
    * The future of product help

    More context about this presentation can be found here:

    • Tom Johnson

      Aaron, thanks for pointing us to your slide presentation. It looked interesting — is that talk recorded somewhere?

      I like the innovation you’re creating with the intersection of social space and technical documentation. Does MindTouch do anything to facilitate these alterntive organization schemes, such as offer tagging or sorting based on custom metadata? I see that you use analytics to pull together the most popular posts, right?

      • Kelly Abbott

        Hi, Tom. I can answer for Aaron here. MindTouch uses tagging as well as a native scripting language called DekiScript to facilitate alternative organizational strategies. One of the organizational schemes you mention above is by business task. In MindTouch, one would tag each article “see:save time” and then DekiScript handles the way that relationship is manifested to the user.

        One other organization schema I’d like to point as it Draft state and Feedback state. At MindTouch we have a method of indicated which articles are in which state relative to their publication status. A single article can have multiple states throughout its lifecycle such. On one path MindTouch gives site owners, product managers, community builders and tech pubs managers the tools to elicit content from users by drafting articles as: State:Idea vs. State:content needed vs. State:draft vs. State:edited vs. State:final. Then when an article gets negative feedback we can add the following states to an article indicating that it might need attention: Feedback:deprecated vs Feedback:regressed vs Feedback:invalid vs Feedback:needs fixing

        The *findability* of content in specific draft states or feedback classifications appeals to some users and some community members as it allows them to own the lifecycle of the content around that topic and maintain it for accuracy and consistency. Clearly the site owners themselves are drawn to this organizational scheme, but so are end users passionate about the products they use.

        BTW, great post. I’m going to be making more recommendations to update our standard tagging library and will reference this post in a set of best practices for our customers.

  • Roger Sharp

    Tom, This is great for brainstorming. Your Pros and Cons article was good too. I’ve never liked the TOC approach and built in stepping-stone navigation whenever I could. I’m using Flare 7 and still haven’t caught on to the KEYWORD concept. If you hammer out that a bit sometime, I hope I find it. @sharpras on twitter.


  • Jen Phillips

    Some very interesting points, and some very good timing, too – I’m in the middle of an update on our help system. It’s an old system that was written by coders, left fallow, refreshed by a very inexperienced technical writer (me a couple of years ago) and is now maintained every few months when I get the chance between everything that’s deemed more important. I simply don’t have the time or resources to overhaul it properly, so each time I look at it I try to improve it a bit as well as updating it to reflect changes in the product. You’ve given me a lot to think about in terms of the overall structure and I suspect the next review will see some significant changes to how the content is organised.

    Thank you!

    • Aaron Fulkerson


      You should consider talking to us at MindTouch. No doubt you’re an expert on content, but we offer a social knowledge base product and/or build next generation help for some of the world’s largest brands (e.g.- Autodesk, Intuit, HP-Palm, Intel, etc…). At the very least you can see how some of our customers are delivering social help systems. Feel free to call me personally if you like: (619)931-2314.

    • Tom Johnson

      Jen, thanks for your comment. The neat thing about alternative structures for organizing content is that you don’t have to rewrite the help to give it a new, fresh look. By the way, I just subscribed to your blog so I’ll check it out regularly now.

  • Marline Hornig

    Right on Brother, great layout, nice opinions, fantastic blog. one in a million. :)

  • Farmsnaskau

    Podniecone dupy czekaja na Ciebie. Wejdz na strone , nie zastanawiaj sie :

    sex laski
    seks do ogladania
    dziwki w londynie
    Ciasne cipcie
    Dymanie laseczek
    Kutasa do buzi
    Mlodziutkie kurewki
    Piekne nago
    Rzniecie film
    Sperma w cipce filmy
    ladne panie

  • abortion clinics florida

    I would like to consider the opportunity of saying thanks to you for the professional suggestions I have constantly enjoyed going to your site. We are looking forward to the actual commencement of my college research and the entire groundwork would never have been complete without surfing your web blog. If I can be of any assistance to others, I’d be pleased to help by what I have gained from here.