I spent the past week in California, interviewing with various companies. In preparation for each interview, I studied each company's documentation as best I could. I noticed two main trends. Some companies group all their documentation together into one massive site. The sites usually have a robust table of contents and include help for most of the company's products. In contrast, other companies segment out their help into smaller sites. For example, a company might have an HTML file that opens a tripane help for each of their 25 products.
To use a metaphor, you can choose between a one-stop-shopping experience, where almost everything is available in one supercenter warehouse. Or you can choose a specialty store model that focuses on a much narrower set of products. Which is the better approach for help content?
One main advantage in aggregating all help content under one roof is centralized search. Users can search in one place and find everything they're looking for. However, if you have 4,000 topics, the search results may not be that useful, especially if you're searching for a general topic (e.g., "Rights and Roles"). The topic you're looking for may be buried in a sea of similar but irrelevant information.
In contrast, with a specialty store model, search results show a more narrowly focused set of results. For example, searching for "Rights and Roles" will return results focused on the product or service you're interested in. Of course, if you don't find the topic, you may second-guess whether you're in the right help site to begin with. Maybe your answer lies within another help system? You may need to run the same search in ten different help files.
Browsing also becomes problematic when you have 4,000 topics in the table of contents (the one-stop-shopping model). Browsing through books and sub-books and sub-sub books and sub-sub-sub books to find the right topic is tedious.
If you expand out all levels of the table of contents, the information starts to look really complex. Users may feel intimidated and overwhelmed about where to even begin. It's too much to learn. Subsequent forays into the help may lead to more familiarity, but not for new users.
With a small store, it's much easier to browse the available products. As long as the user can find the right store, or the right entry point into the help, the experience navigating the information will be much more pleasant. The smaller table of contents won't be as intimidating, and users can more easily browse content in an approachable way.
While a massive table of contents can make browsing more difficult, it does have a unique advantage: it helps users realize what they didn't know. A while ago, I noted that users don't know what they don't know. If users don't know about product Z, but discover it while browsing for help with widget M, you've helped users find new information they might not have discovered if you hadn't aggregated both product Z and widget M's help on the same site.
In short, aggregating content on the same site allows you to cross-promote other products. You can have a list of related links that allows users to see similar topics in products and services they hadn't even considered.
The downside with cross-promotion is that you may end up presenting users with a lot of irrelevant information. Users may not be interested in getting help for products or services they're not using, and seeing these "related" links clutter up the help content might be distracting.
If you group all content in one site, designing and maintaining the site gets a lot easier. If you change one element of your site, such as your layout or style sheet, all content automatically receives the change. If your site is database driven, you have to update or back up only one database rather than dozens.
In contrast, if you have 25 different help files, you would have to update the same layout or style sheet across all the sites. In my previous job, I had seven main products I maintained help for. When I made a small change to one help file or style sheet, I had to regenerate the content for all the other sites. It was a major pain.
Once your help layout and style sheet are frozen, changes may not be such a big deal, but my sites were continually evolving, so the maintenance was cumbersome. You can also set up build scripts that automatically rebuild all your help files and publish them on a regular basis, but you then risk introducing errors unless you check the outputs.
The all-in-one model poses special challenges with naming conventions. Because a search for "editing preferences" may return a similarly named topic for several different products, you need to add the product or service name in parentheses after the title, like this: "Editing Preferences (Product Z)". This naming convention can get a bit annoying from a stylistic point of view, because it uses parentheses in a non-standard way.
On the other hand, adding the product name in each title makes the content much more search engine friendly. You're stuffing the right keyword into one of the most important elements of the page.
With specialty sites, you won't have the challenge of providing unique names for all your topics. You can just write "Editing Preferences." However, you also lose out on the SEO benefits that come from coupling product names with each topic.
You might ask whether my either/or scenario here is a fallacy (either one-stop-shopping or specialized stores). Is there another option?
Yes, there are more options. Let's say you have a web content management system (CMS) platform. All the content is stored on the web CMS, but you have different entry points with different tables of contents. Each entry point takes you to a different view of the content (with a different table of contents), but ultimately all the content lives on the same site. Search results can mix the results for all the content, or allow you to narrow down the results to a specific product only.
Systems like SharePoint and Confluence solve this problem by providing different "spaces" within a larger space. Each space can have its own permissions and visibility settings, while also allowing users to search the larger space if desired. Sometimes the smaller spaces can be excluded from the larger spaces if permissions restrict the smaller space's visibility.
While this setup seems ideal, anyone who has been immersed in a SharePoint environment probably has mixed feelings about it. SharePoint is convenient but also frustrating at the same time. Configuring permissions may be tricky. Maybe some subsites optimize their content better and trump results from more important sites. Users may not be able to narrow the results to just show what they're looking for.
Faceted browsing and filtering can help sort out results and allow users to narrow the view on a specific product, but few tools offer faceted filtering out of the box.
Whether you choose a one-stop shopping model or a specialty store model depends on your help products. If the products are totally distinct from each other, it doesn't make a lot of sense to group all of this help together. But if your products are related, grouping them together can bring a lot of advantages.
Although I'm a bit divided, I lean more towards a web platform model that houses all content on the same site but presents different tables of contents for different products. I think search engines can provide better tools for filtering and sorting search results based on different products.
I don't like the idea of having 25+ separate help systems to maintain. Most sites on the web seem to avoid this model. Keeping help contained in static sites with links on web pages seems a bit outdated to me.
I'm curious to hear about your approach to help. Do you centralize all your help on the same site, or do you break it up into smaller, more specialized sites?
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in , API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.