The focus of indexes

[Rowena Campbell <campbell -at- ANGIS -dot- SU -dot- OZ -dot- AU>]

On the subject of indexes and their focus:

These comments don't apply to Bonni Graham's index, or document, because
judging from the postings she's sent she knows a lot about the subject (and has
a great deal more experience than I, I'll warrant!).  However, I have used
the points that she has raised as a hypothetical case (without knowing the
particulars of it).  This is an issue that I feel strongly about and I'm in a
mood to opine ...

I agree that "indexes should focus on people's tasks, and use the terms
they're expecting to find".  I think this is very important.

>1) The manual documents the program.  If the index does not focus on
>   the topic of the book, what good is it?

Granted that the manual is for a program - what else are manuals for? - and
the index must focus upon the subject matter of the volume.

Unless the program was intended for a technically sophisticated audience -
is it safe to assume that the manual was meant to tell the users how to use
the program to achieve some specific end? Or was it intended only to tell
them how to use the program - this, presumably being sufficient end in
itself? If so, that's a one almighty important program you've got there!

>2) The program the manual describes is NOT replacing a task that is
>   currently performed on paper.  It is creating an entirely new task
>   that bears very little relationship to how things are done on paper,
>   but has nevertheless been lacking in the profession previously.  So
>   how can I use terms that are equivalent to the tasks the user is
>   already familiar with when those tasks are not what the program does?

Surely the tasks that the program achieves have some theoretical basis in the
users' profession, outside of a computing application?  Or is the program a
computing application only, without reference to other subject matter? If the
latter, then my following comments do not apply.

Assuming the program achieves some professional goal outside the realm of
computing, then there must be terms within the vocabularly of that profession
that give an immediate idea of the functions of the program before the user
ever starts using the program or reading the manual.  These are the important
terms and the ones that must be used in the index.

It is difficult to discuss these things in a hypothetical way for so much
depends upon the audience.  We all know that the number one criterion of good
writing is to keep the audience always in mind!

If the users have a large amount of time to devote to working out how to use
an apparently quite radical program, then it may be appropriate to write
almost exclusively from the program's point-of-view.  But if they are busy
(like my readership, busy and pressured and overwhealmed with work) and have
many other tasks to perform, and if computers are not the first tool that
they use in their job, then they will appreciate some source of quick
reference that tells them where to find something that will do what THEY want
to do, and not oblige them to go "back to school" for the fifteen-hundreth
time before they can figure it out!

So many manuals that I have encountered are written as if that one program
were a revolution that was shaking the earth, and all of the profession would
stand stock still to look at it.  When you're dealing with over a hundred
programs, like I am, you get pretty bloody sick of manuals that put the onus
on the user to figure out what to do with the program, because the writer has
nicely (actually, rarely nicely; usually obscurely and very incompletely) set
out the modus operandi of the PROGRAM.  And really - your non-computerbuff
user just doesn't care about THE PROGRAM per se.  They really are terribly
disloyal in this, for they only care about WHAT THEY CAN DO WITH IT!

>3) My idea for the index, given number two above, was that the user
>   would be using the manual in conjunction with the program.  If they
>   came across a program task that they weren't sure how to do, they
>   would go to the manual, possibly via the index.  In which case, the
>   index should match the terms in the program as closely as possible.

Very good, I agree exactly.  But the index should ALSO contain additional
terms - terms that convey what the program does to a person who is not using
the program (even if this must be only in a general way). Also please don't
assume that the reader is going to use the program or manual in any set order
that we might have in our minds.  The utility of an index lies in allowing
the user to jump to the feature of interest to THEM personally and whenever
they feel like it!

>How can you include familiar tasks in an index for a manual that is
>revolutionizing a professional area, rather than simply automating an
>existing process?

If the program's tasks really have no correspondence to non computing
activities, then ... I'm really stumped.  You'd have to use the terms that
are appropriate to the task.. and if there really AREN'T any terms outside
those used in the programs .. what CAN you do?



Rowena Campbell
campbell -at- angis -dot- su -dot- oz -dot- au