Re: Troubleshooting Documentation

["David M. Brown" <dmbrown -at- BROWN-INC -dot- COM>]

Carol Turner wrote:
>
> For an intranet I'd probably write it as an HTML Help system,
> with a very complete index...
>
> ----------
> > From: Marshall, Elizabeth <EMarshall -at- WCOM -dot- NET>
> >
> > Was wondering if anyone could recommend a resource for how to
> > write troubleshooting documentation?  ... It is going to be
> > published on our company's intranet.
>

As a long-time user of Word (and occasionally FrameMaker), I'm used
to embedding index entries in source files, then re-creating the
index whenever pagination or content changes.  When I started working
with HTML, though, I couldn't find any equivalent.

Some search engines used "keywords" META tags to enhance searching,
but there were still serious shortcomings:

 *  Consistency.  As you worked on your keywords, there was no way
    to see all of them at once to ensure consistent terminology and
    coverage.

 *  Access.  META tags provided file-level access, but there was no
    way to associate keywords with targets *within* an HTML file.

 *  Usability.  Although an improvement over full-text search,
    keyword-based search engines still required the user to "guess"
    at entries.  This "virtual index" lacked one of the key
    benefits of a traditional "back of the book"-style index (in
    which all the entries are laid out for you, so you can see items
    such as synonyms that don't actually appear in the source files
    and that you might not have thought to search for).

 *  Maintenance.  Every time the source files got rearranged (in
    content or file hierarchy), I had to go through the index file
    to check for broken links.  As a result, I had less time to
    spend creating meaningful entries for new material and making
    sure the updated index was still as consistent and usable as
    the original.

Microsoft's proprietary, ActiveX-dependent HTML Help lets you add
index entries to your help topics and creates an index much like the
familiar Winhelp "Search" tab.  For standard HTML, though, there have
been no such tools; but that's about to change.

Brown Inc. is developing a program that fills this gap in the HTML
developer's toolbox.  For more information, please take a moment to
visit http://www.brown-inc.com/indexer/FAQ.htm and read about
HTML Indexer(tm).

--David

P.S.  I hope no one objects to the arguably commercial nature of
      this message.  Before posting it, I checked with TECHWR-L
      list owner Eric Ray, who agreed that it was on-topic and
      likely to be of interest to list subscribers.

 ==============================
  David M. Brown -- Brown Inc.
     dmbrown -at- brown-inc -dot- com
   http://www.brown-inc.com/
 ==============================


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=