RE: indexes

Subject: RE: indexes
From: Janet Valade <janetv -at- systech -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 24 Mar 2000 15:02:05 -0800


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 Valade
Technical Writer
Systech Corporation, San Diego, CA
mailto:janetv -at- systech -dot- com

Previous by Author: RE: Mentoring feature on the TECHWR-L site: You got it! (was: Re: Mentoring)
Next by Author: RE: Are we WRITERS????
Previous by Thread: RE: Indexes
Next by Thread: indexes

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

Sponsored Ads

Sponsored Ads