Re: Troubleshooting Documentation

Subject: Re: Troubleshooting Documentation
From: "David M. Brown" <dmbrown -at- BROWN-INC -dot- COM>
Date: Wed, 5 Aug 1998 14:10:31 -0700

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=



Previous by Author: Re: purpose of arrows --> (was Insert-->Arrow...)
Next by Author: Re: Troubleshooting Documentation
Previous by Thread: Re: Troubleshooting Documentation
Next by Thread: Re: Troubleshooting Documentation


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


Sponsored Ads