TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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?
-kevin
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?
