Re: Online documentation, problems using

[Robert Cianchette <rmc -at- DAVIDGE -dot- COM>]

(stuff deleted)

>I am curious to know what technical writers think of online indexes as they
>currently exist.  Are your documentations indexed by a professional indexer,
>the software developer, or a tech writer?  I have found that these three
>categories have three different agendas for indexes.

>On the other hand, someone recently said to me that he thinks online
>indexing will become obsolete, because full-text searches are possible.  I
>tried to explain how a good index saves the researcher so much time, but
>this particular historian wasn't buying it (something about wanting to see
>all the "false hits" himself and not trusting the indexer to evaluate
>relevant material).

>Any comments?

>Barbara E. Cohen
>Professional Indexer
>becohen -at- well -dot- sf -dot- ca -dot- us

Quick introduction:  I'm a technical writer for a small (20 people) software
development/VAR company that produces automated trading systems for the
brokerage industry.  I fell into this position after a variety of educational
and work experiences.  I'm the first person to hold this position, and getting
things rolling has not been particularly easy (I've been here for 16 months.)
I have little authority and few tools to work with (I use Microsoft Word as
my "Desktop Publishing" software!), but I truly enjoy the work.  I'm not a
member of STC (yet), so I'm very happy to have this channel for communicating
with other people in the field.  Thanks, Eric.

At this point we don't produce online documentation (not to be confused with
the few, less than helpful "help" screens that the programmers have written
on a whim.)  But, I think my general approach would have to be similar to my
approach to paper documentation.  Online documentation (meaning a replacement
for or equivalent of a printed manual, as opposed to online help, which is
equivalent to a quick reference card) should, in my opinion, be complete and
heavily indexed.  I'm not a subscriber to the theory that less is more when
it comes to documentation.  Granted, many users will never read it, and many
others don't have the skill or patience to find what they're looking for.
But, those that _will_ use it will rightly expect to find the answer to their
question.

While the ability to perform free-text searches may lessen the need for
complete, well-written indexes, it doesn't make them obsolete.  If the
documentation doesn't use common terms to describe operations, you are
not likely to find what you're looking for with a free-text search.  For
example, if database documentation doesn't use the term "import" for adding
data to a database from a non-native file, I'm not gonna find what I'm
looking for, because that (to me) is the common term.  If there is an index,
I can at least look through it (cursing all the time) to see what these
idiots have chosen to call the "import" function.  (In case you can't tell,
this example is from recent personal experience!)

So, Barbara, here's a voice in support of your talents.  Along this line,
I would appreciate it if you or anyone out there could provide me with a
reference for a good primer on indexing.  Although I have a degree in
Library and Information Science, I've never taken an indexing course, and
I could really use some pointers.  Thanks.

Robert