Search results

Implementing Faceted Classification/Search with a Help Authoring Tool [Organizing Content 7]

Series: Findability / organizing content

by Tom Johnson on May 21, 2010
categories: findability technical-writing

In my last post, I presented faceted classification and faceted search as an alternative method of organization for help content. While faceted navigation systems are common on the web, implementing a faceted navigation system to describe help content using one of the common help authoring tools, such as Flare, RoboHelp, Author-It, Doc-to-Help,  is more challenging.

Faceted Browsing

According to Tony Self, one of the strengths of a help authoring tool (HAT) is the table of contents (TOC) feature. Through the TOC, you can easily create a quick system of navigation.

It's common to use this TOC to create a system of topic-based containers for users to navigate, but there's no reason why you couldn't instead dedicate the folders to facets. In the prototype below, each of the "Browse by ... " books in the left pane represents the facets by which users can navigate the help content.

Faceted browsing system showing alternative methods of navigation
Faceted browsing system showing alternative methods of navigation

Users can browse the content by the following facets:

  • Browse by Topic. Topics are arranged in the traditional topic-based, hierarchical containers.
  • Browse by Role. Topics are arranged by role (super agent and regular agent), and then broken down by topic containers.
  • Browse by Skill Level. Topics are broken into two books, Advanced and Beginner. And then most likely broken down by topic containers.
  • Browse by Popularity. Only the top 20 most popular topics are listed.
  • Browse by Concept or Task. Topics are divided into concept and task groupings, and then probably broken down by topic containers.
  • Browse by Status. Topics are organized by facet. (In Swordfish, statuses play a prominent role for operations. Depending on the status of the operation, you can perform certain tasks, so this provides a way to organize the tasks.)
  • Browse by Help Format. Topics are divided into video, diagram, and FAQ groupings.
  • Browse by Problem. Topics are arranged by problem, somewhat like a troubleshooting grid.
  • Browse by Screen. Topics are arranged by screen. These are the context-sensitive help topics.

Almost every HAT allows you to create multiple TOCs. Each of these facets is simply a secondary TOC that is integrated into the master TOC.

One of the problems with these facets is that they don't entirely get away from the topic-based containers that I am resisting. With 200 topics, I can't simply divide all topics in the help into two groupings, such as Advanced and Beginner. A second tier facet is also necessary, and the only second-tier facet that makes sense is the topic container.

However, some inclusion of topic containers isn't necessarily a bad thing. The main reason topic containers fail is because of the abundance of topics. In small help systems, the topic containers provide easy navigation and aren't as frustrating for users. The first facet, such as Advanced or Beginner, breaks down this large number of topics into a smaller subset, which makes the navigation more feasible.

Faceted Search

When a user clicks the search tab and searches for an item, the user can narrow the search results by using similar facets, as shown in the following image.

Faceted Search
Faceted Search

I'm not sure how it would be implemented in other HATs, but in Madcap Flare, you can tag each topic with a keyword (this is called inserting Concepts). You can then add this set of tags/concepts below the search box by adding a "Search Filter Set" to your help.

The challenge here is to provide the same facets that users get by browsing. Tags work a bit differently than TOCs, but the idea is the same. You can limit the search results by the following:

  • Regular Agent Role
  • Super Agent Role
  • Advanced Level
  • Beginner Level
  • Conceptual Topics
  • Step-by-Step Topics
  • Most Asked About
  • Video Format
  • Diagram Format
  • FAQ Topic

Not all of the TOC facets end up as tags. The Browse by Role facet has two roles, so I can tag topics within these books as either a Regular Agent Role or Super Agent Role.

The Browse by Skill Level facet has two levels, Beginner and Advanced, so I can tag the topics within this facet as Beginner Level or Advanced Level.

For the Browse by Concept or Task facet, I can tag the topics as Conceptual Topics or Step-by-Step Topics.

The Browse by Popularity is tagged as Most Asked About (or Most Popular).

Finally, the Browse by Format allows me to tag the topics as Video Format, Diagram Format, or FAQ topic (these are the only three main formats in the help material apart from the concept/task distinction).

Shortcomings of Faceted Search

One of the most difficult problems with setting up faceted navigation is to identify facets for information topics. With merchandise or other products, you can often identify a clear set of attributes that define the product. With shoes, you can classify and filter the shoes by brand, style, color, cost, gender, sport, size, and other qualities.

With Google, you can classify the content by a plethora of information formats, including news, books, videos, images, maps, discussions, shopping, blogs, twitter ("updates"), and more.

In a library, you can classify books by author, publication date, genre, period, subject, book type, etc.

Help topics don't seem to have a set of clearly identifiable facets. Some of the facets that you could classify a help topic with -- for example, length, format, reading level, information type, corresponding screen, etc. -- aren't that helpful to users.

Help content is, however, rich in topics. But using topic tags as the attributes seems like the same game as the topic-based, hierarchical containers. For example, look at the faceted search filters that I've circled in the following image.

Topic facets on a search for a topic seem redundant and confusing to me
Topic facets on a search for a topic

If a user searches the help for "run a black operations campaign," what benefit is there in limiting the results to the facet "Related to black ops"? Won't the results already contain black ops topics?

Further, what if a user searches for "coordinate informants for black ops"? Which facet would I then choose to limit the results -- Related to Black Ops or Related to Informants? It's the same problem as the topic-based, hierarchical containers.

Searching for a topic and then limiting the results by topics seems redundant to me.

Moreover, if these facets are simply topics, there's a likely chance that you'll include dozens of topics. Adding too many topics in the Search Filter Set will bloat the number of search facets beyond what is usable. If you look at the search filter set in Flare's online help, you'll see that they use about 80 different topics in their search filter set, which seems excessive.

It's clear that faceted classification and faceted search have benefits for many product websites, as well as for many information-heavy websites with many types of content. But the lack of a clear set of facets for help material makes it more challenging to implement in a way that is clearly beneficial.

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.