Re: Index/TOC Needed in HTML &/or Browser-Based Help?

Subject: Re: Index/TOC Needed in HTML &/or Browser-Based Help?
From: doc -at- edwordsmith -dot- com
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Sun, 21 May 2006 01:12:59 -0700

On Friday 19 May 2006 13:39, Barbara Vega wrote:
> Hello all
> I have been told that in the Microsoft Vista version to come out, the
> TOC and Index have been eliminated, in favor of a much more efficient,
> improved search engine.

This is a good thing because:

1. No project I've worked on in the past decade has budgeted for indexing.

2. Many alphabetic indexes I've used have not provided the expected level of
convenience. Haltingly, begrudgingly, I've relinquished some of the
comfortable old notion of a back-of-book index as a result of diligent
indexing that provides an appropriate index into the contents of a book.

3. Until authors start thinking outside the style guide, the TOCs will
continue to be automated outlines lifted verbatim from perfunctorily
style-driven headings: "I. Getting Started" Who cares? If dispensing with
the TOC is in any small way a step toward more informative titles and
heading, then I couldn't be more pleased. Have I offended anybody?

4. Full-text indexing is the only way to go and has been since oh, say early
1990s. IIRC, the original Windows Help didn't feature full-text indexing,
and MS didn't add it as a regular Help feature until Windows '98 Help, but
for some years prior you could add a full-text index into a WinHelp help file
by copping a couple of Video for Windows DLLs and jiggering an option or two
in the project configuration and Help compiler.

As for traditional features like TOC and alpha index, I think they add value
to printed material, but not to Help files. A TOC for an especially complex
Help file is welcomed by me, and the expanding TOC tree (the one where you
click the little (+) sign next to a topic to expand it) is a nice touch when
a TOC is called for, but for run-of-mill (half-assed, incomplete, rush job)
help files, an expanding TOC is just affectation anyway.

5. About the taxonomic approach to infomation, I think it is about time! and
I will be happy to give it my endoresement once I've seen it applied
effectively by Help authors. Taxonomy does come with its own set of
problems, familiar to you already if you've ever needed a librarian to tell
you what subject in the card catalog to look under to find the topic you're
reseraching, or if you've dabbled in scientific taxonomic theories like
cladistic analysis (e.g., would you classify the proverbial red-headed step
child as progeny or redhead?). Bless the biologists for inventing taxonomic
science, but I foresee abundant opportunities for hairballs of ill-considered
taxonomy in help files, unless Windows' topic taxonomy is accompanied by
rigorously developed taxa and rigorously-applied guidelines for sorting
topics into them. Maybe we can hope for something slightly less confining
that a standard taxonomy to guide Help authors in their analysis of Help
topic taxonomy.

I think it would be awesome to retrain some Type A zoologists as tech writers,
and give them the job of developing taxonomies of programming objects <vbg>.
I wonder if Grady Booch got his start that way?

Ned Bedinger
doc -at- edwordsmith -dot- com

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!.

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

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

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

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


Index/TOC Needed in HTML &/or Browser-Based Help?: From: Barbara Vega

Previous by Author: 'Entire' Vs. 'Whole'
Next by Author: Re: Taxonomy (was Re: Index/TOC Needed in HTML &/or Browser-Based Help?)
Previous by Thread: Re: Index/TOC Needed in HTML &/or Browser-Based Help? (take II)
Next by Thread: Taxonomy (was Re: Index/TOC Needed in HTML &/or Browser-Based Help?)

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

Sponsored Ads