Organizing Help Content: Breaking Out of Topic-Based Hierarchies

by Tom Johnson on Mar 21, 2011
categories: findability • technical-writing

At 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?

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.

Search

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.

Conclusion

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.