Making WebHelp topics findable

Subject: Making WebHelp topics findable
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 29 Mar 2013 14:19:44 -0400


Our docs are webhelp/html5-ish, created with MadCap Flare, and are stored and browsed on the customer's local file system. Never on the web.

I've been asked to do some re-org and consolidation (getting rid of a Concepts section, among other changes).

So, the ToC has nesting as little as one or two layers deep, and as many as four deep... at least.
Some topics are bigger and more complicated than others, thus the categorizing and nesting.
Also, we'll be resurrecting a PDF option this year, so we NEED to have levels of organization that correspond to chapters and sections and subsections.

My question: What methods do y'all use to make certain pages/topics REALLY easy to find?

I do have plenty of index entries for the topics that particularly interest my reviewers.

But, in the ToC, there's a certain (I think) natural order to the material that keeps some of those pages rather deeply nested.

ALSO, while the Flare-supplied search utility has become more Google-like in the appearance of its results (since version 8), the power isn't there.
So, a page like "Lost authentication tokens" is found by searching "lost", but it appears as hit number 31 of 111 (so, well below the fold).
If the user adds terms, e.g., searching for "lost authentication token", that just pushes the desired page down to number 74 of 390 hits... even worse.

I know what I would be doing if I wanted to improve SEO for a page or a site on the WWW. But this isn't the web. This is the customer's own workstation or their intranet, at best.

One approach I've tried is to make MANY discussions/instructions into Snippets, and then call those snippets from several pages, scattered throughout the project. This lets me give different titles - and therefore different ToC locations for the same material, without de-railing some other features (like breadcrumbs). But that can go only so far before it starts looking like clutter for the ordinary user. Also, it gets hard to re-classify things in usefully different ways.

For example, if you disobeyed the [relentless to the point of overkill] admonishments to make backups of your critical authentication tokens and store the backups off-site, you might lose one. If you lost a physical object, you know that the problem is ... well... that it's lost. You want to know how to recover from that. Does losing something belong in "Troubleshooting"? I mean, there are only so many places where you can put a given piece of info, legitimately. Now multiply by dozens of multi-paragraph sections of info that a customer might urgently wish to find.

As much as I appreciate the "every page is page 1" philosophy, it's directed at the content and organization of the individual pages in Help. Within the overall document or help system, every page simply _can't_ be page 1.

So, what would you say are your favorite strategies and tactics for getting information discovered, when needed, and how would you prioritize the strategies and tactics that you use most?


The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.

>From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?

Learn more:


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Previous by Author: RE: Purpose of Tech Comms today
Next by Author: RE: Who is an ESL writer?
Previous by Thread: TechWhirl: Technical Communication Recap for March 29, 2013
Next by Thread: Commenting Code (was Re: An interview question)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads