RE: indexes

[Janet Valade <janetv -at- systech -dot- com>]

John,

I understand what you are trying to say, but I am forced to disagree. As
someone who digs information out of books often, the scarsity of good
indexes drives me insane. I have an assembly language book that has about
1000 pages with about 5 pages of index. That poor book is battered and
bruised from flying across the room and smashing into the wall.

<a section of the book to find a section of the book">

This is a TOC. An index is a different section with a different purpose. An
index is a section of the book to find a specific item of information. They
are different beasties with different purposes. Even for a very clearly
organized book, an index is a short cut. It saves me the time of having to
figure out the organization and drill down to the little piece of info that
I want.

Suppose I am looking at the source code of a program, trying to figure out
what it does. I come across a function, ioctl. I do not know what this
function does. I pick up my trusty C book and open the index to i. It's not
there! Now what do I do?! I look at the TOC, with it's clear organization,
but where do I look--I/O, flow control, system calls, networking, data
types, string functions? How do I know if the book even discussed ioctl
anywhere? I'm sure your C book would have a TOC entry for the section that
contained a list of functions (something sorely needed by a lot of books)
with summary descriptions, but an index entry would have been faster.  

Suppose I am writing a C program and I know that ioctl will do what I want.
But I can't remember what it returns. Or I can't remember in which order the
arguments should be passed.  So, I look in the index for ioctl. I dont' find
it. After I finish cursing, I go to the TOC. I think it is probably in the
I/O section. I go there. I skim through all the commands in that section and
don't see it. I skim again. Aha! There it is. So, in this case I could find
it, but an index entry would have been a useful shortcut.

While I'm on the subject, I also want to complain about indexes with too
many entries. If I look up XX in the index, I don't want to see 60 pages
referenced. An index should not be a listing of every mention of every word
on every page. It is a pointer to information, not words. I should find, at
most, 2 or 3 entries for XX that point to the pages where XX is explained,
not a list of pages where XX is mentioned peripherally in passing. 

Janet

Janet Valade
Technical Writer
Systech Corporation, San Diego, CA
mailto:janetv -at- systech -dot- com