Two Competing Help Models: One-Stop Shopping or Specialized Stores?

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.

Two strategies for organizing help content

Two strategies for organizing help content

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?

Search Advantages

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.

Cross-Promotion of Other Products

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.

Maintenance and Design

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.

Naming Conventions

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.

Other Models

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.

The Verdict

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?

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.

  • Mark Baker


    I would look at this slightly differently. To me, “sites” are insignificant. Google does not return sites, it returns pages. Readers are seldom paying attention to what “site” the page they land on belongs to. Every page is page one.

    To me, the question is, how do you contextualize each page of your help. The classic tri-pane answer has been that you contextualize it in the book or topic collection by publishing it in a frame side by side with a frame containing a TOC.

    To me, your question boils down to: how much stuff do you put in that TOC.

    My view is, a TOC is not context. Context is about where the subject matter of your topic fits in the overall subject area. If we take that approach, then the question is not do you use one site or many, but do you cover one subject area or many. The former is a question to which the answer is necessarily arbitrary. The latter is a question whose answer can be grounded in reality.

    • Tom Johnson

      Mark, interesting analysis. If I understand you correctly, you’re saying that instead of adding the context through the TOC, we should add it to the page itself.

      I was going to add more specific examples in this post but decided not to. However, I’ll add them here. Check out Palantir’s documentation and compare it with Salesforces’s documentation.

      Palantir’s approach (at least for this documentation) is to centralize it on one site, as far as I can tell. Salesforces’ approach is to break the content up into individual help files. I believe Salesforce used to have a model where everything was aggregated on one site, but then they broke up the content into smaller files because no one could find anything (at least that’s what someone explained to me, though I could have misinterpreted).

      Looking at some of the Salesforce content, I thought about your frankenbooks post and how people sometimes write for the wrong media. The topics are bursted from a DITA topic approach that chunks the content into pieces too small to stand coherently on their own without the supporting context from the TOC. I think most writers follow this same method: making the topics small and providing more context through TOC links.

      However, I don’t think users enjoy clicking around in a massive TOC. The general navigation on most websites doesn’t stack information heavily into various books in a TOC. Instead, you have second and third levels of navigation that appear only when you get to that level.

      Anyway, what do you make of these two approaches to documentation? Would you revamp the content to have a lighter TOC and many more sections on each page? That was my general approach when I wrote help for the LDS Church apps (see an example here). I really like using drop-down hotspots to compress information on a page. Madcap Flare has them built in, but I could easily use jQuery to accomplish the same thing.

      • Mark Baker

        Hi Tom,

        I don’t like either. But the way in which each is unsatisfactory does help to demonstrate how the book model is unsatisfactory on the web.

        Any one topic in an information set has subject affinities to many other topics in the set, and to subjects outside the topic set. A table of contents can only express one of these subject affinities. Unless the subject affinity the reader wants to explore next is the one that the TOC happens to express, the TOC is useless to them.

        The larger an information set becomes, the more diverse affinities it contains, and so the worse a TOC performs as a means of navigation. But breaking up the set into smaller pieces to try to make the TOC work better just means that even fewer of the subject affinities are being represented and made navigable.

        The context of a topic is made up of all of the subject affinities it contains. A TOC, which can only express on affinity, is therefore a poor tool for establishing context.

        Consider this very brief Wikipedia article on the Manicouagan crater in Quebec:

        Here are just a few of the subject affinities it has:

        * Geographic coordinates
        * Municipal location
        * Place in time
        * Relationship to historical events (extinctions)
        * Scholarship
        * Geology
        * Astronomy
        * Photography from space

        If it were to be placed in a TOC, which of these affinities should be choose to locate it in the TOC?

        Online, there is no limit to the subject affinities we can express and navigate. Wikipedia expresses and makes navigable all these affinities with the following simple devices:

        * Rich linking of the text itself
        * Standard templates for various types of content, with links to subject areas of the fields in the templates.
        * Placing the content into categories and providing a navigable overview of the category.

        With these simple tools, Wikipedia provides a far more robust navigation of a far larger body of content than any tech doc set on the planet.

  • Yaakov Simon


    Good thought-provoking post. I immdiately started thinking about PDF guides and a one-stop shop vs. the boutique model. The point about “cross-pollinization” of products is important. A customer uses product A and is ignorant about the advantages of also using products B and C.

    Mark – I don’t really understand the point you are trying to make. The larger a TOC or web-site is, the less usable it is. Even if I get to a page with a Google-search, I might still look at other pages in that site. I agree with Tom that it is important to consider the pros and cons of each approach.

    • Tom Johnson

      Yaakov, thanks for commenting on this post. I think cross-pollination is an important concept that we should explore more. Basically we ask, how can we let users find not just the answer they want, but also present users with information they might not even know.

      Which approach do you follow in the help content you create — everything on one site, or a collection of small sites?

  • Dan Schulte

    I think I understand what Tom is saying, and it is a very good point.
    Parphrased, the article/page is not containt within a TOC, the article IS the TOC.

    Example; lets say there is an article about how to use an iPad tablet as a teaching aid in high school. Well, there are a few affinities here that the reader may choose to explore; they might want to explore using other types of tablets as teaching aids; they might want to explore how to use iPads in a teaching/training environment other than a (high) school; or they might want to explore what other technologies can be used for training aids.
    Three affinities:
    1. Types of tablets used as a teaching aid.
    2. Tablets used in various types of teaching/training environments.
    3. Technology than can be used as a teaching aid.

    With TOC would you present?
    If you have various links and category tables embedded in the article itself, then the reader can choose which direction they go in search of more knowledge; based on their interest and needs.

    In context of your question; one category table could list 1. Other products that perform similar functions (e.g. tablets) and another would list 2. Other products that would be used in that application (e.g. teaching aids). And, wouldn’t a business want to present a customer with at least those two options for seeking more information; if not more?

    A TOC can’t do that; but luckily, pages on today’s websites are more than an electronic PDF; and the idea of a TOC might just be obsolete…

  • Pingback: A New Approach to Organizing Help - Every Page is Page One()

  • Pingback: Web Organization is not Like Book Organization - Every Page is Page One()

  • Pingback: Structured Authoring Versus the Web? | I'd Rather Be Writing()