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.
Kevin Elmore wondered: <<How shaken would your confidence be if an
entity's help files did not have a proper index?>>
I wouldn't be surprised in the least, since many of the indexes* I
see are poorly done -- difficult to read, and hard to find the
desired topic. But I would be pissed off. People who don't create
indexes often justify it by appealing to the usefulness of the search
function. It's worth remembering that search functions only work if
you know the right jargon, and if you have some experience building
effective searches. Most people don't know the right jargon, and
fewer than we think know how to craft effective searches, so searches
often fail.
* Note a slight usage distinction: particularly in U.S. English,
"indexes" seems to be the preferred plural for back-of-book indexes.
"Indices", on the other hand, tends to be used more for calculated
values, such as price indices. Not a hard and fast rule, but a common
one.
<<... in short, our index is now just another way to search for text.
I've brought this up, but there is no way we'll get a professional
indexer in to create a new index.>>
You don't have to be a professional to create a good index. It takes
a bit of study, and a lot of practice, but you can get good results
surprisingly fast if you're willing to make the effort. I do all my
own indexes, including the one in my recent book (see below), and
although I recognize that they could be better, the bottom line for
me is that they're generally effective. People use them without
complaint. That's really all I care about.
<<People are now used to searching for numbers and entire titles.
Our index is a hybrid of the Table of Contents (scrolling through the
first letters of a title) and the Search function (locating topics
through using keywords). All in all, it works for our internal
users, and that is important enough. But… There is a good chance that
we will publish a new help file output based on this project... This
help file will be seen by a client of ours. It would no longer be
just for our internal users.>>
It's important to take a large step back and remember something: a
sufficiently motivated user will eventually figure out how to find
the information they need (usually by Googling, asking the geek down
the hall, or buying a "for dummies" book). So you could use the same
logic often used to dispense with an index to dispense with the
documentation, and people would still get the job done. Will they
praise your name and smile while they're doing it? Not so much. Will
they praise your name and smile just because you created a kickass
index? Not so much either. But at least they won't be cursing you
quite so often.
<<Upon this realization, I have requested from management that we do
not produce the index. Publish only the Table of Contents and the
Search tab. I am ashamed of our index, as it really only an index by
name. It does not look professional to me.>>
If your table of contents is extremely well organized, and
comprehensive, it may be all that anyone needs. It's arguably less
efficient than a really good index (because people have to skim the
whole thing instead of going right to a single keyword or its
synonym), but they'll get there eventually.
It's also worth noting that not everyone uses or appreciates an
index. Some people really do prefer the search tool, and only use the
index when they're desperate. (Some of them have posted on this topic
here on techwr-l.) But for those, like me, who rely heavily on
indexes, you shouldn't be separating them from that support just
because you don't want to make the effort to do a good index.
----------------------------------------------------
-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
www.geoff-hart.com
--------------------------------------------------
***Now available*** _Effective onscreen editing_
(http://www.geoff-hart.com/home/onscreen-book.htm)
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. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
