Re: Indices and not-indices

Subject: Re: Indices and not-indices
From: "Julie Stickler" <jstickler -at- gmail -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 22 Jul 2008 14:19:33 -0400

I'll vote for ugly index over no index as well.

I'm a big fan of indexing. And not just because I use indexes
extensively and would miss them if I didn't put them into my own docs.
Even if my users never opened my index, I've found that the process
of building an index is a good final check for my documentation.
Indexing can help me identify missing topics, or even just
information that I included in one topic, but left out of another.
And I'm just anal retentive enough to enjoy building indexes. *grins*
The fact that a good index is helpful to the user is almost an added

Indexing doesn't need to take a lot of time. When I wrote my first
manual (which weighed in at about 400 pages) I spent two days building
and tweaking the index. And it doesn't have to be perfect right away.
I plan two or three days for indexing a project, be it a manual or a
help system. I usually do my indexing during that couple of days
when the docs are out for review and I'm waiting for edits and
comments to come back. After a couple of releases, I usually get to
the point where I had a damn fine index. When people would ask me if
X is in a particular doc, I usually can just check my index to see if
the information is there or not.

As far as building an index, it's all about keywords and anticipating
what your users would be looking up. I usually try to create two
keywords for each heading or topic. I create index entries for each of
the UI elements (applications, tabs, buttons, actions, etc.). I
create an index entry for each task that can be performed with the
software (widgets: buying, creating, selling, etc).

Then the fun part comes in. What alternate terms or keywords (words
that don't appear in the documentation) might they be searching under.
This is where an index can provide real value by pointing the user to
a topic that they can't find using search.

And I've found Larry Bonura's The Art of Indexing to be a really
excellent book on the subject.

Julie Stickler

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

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-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 admin -at- techwr-l -dot- com -dot- Visit for more resources and info.


Indices and not-indices: From: Kevin Elmore
Re: Indices and not-indices: From: Jay Maechtlen

Previous by Author: Re: the benefit of documentation
Next by Author: Re: Poll: Provide documentation in PDF & Help formats, or only in Help formats?
Previous by Thread: Re: Indices and not-indices
Next by Thread: RE: Indices and not-indices

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

Sponsored Ads