How to write a good index?

[Jeanne A. E. DeVoto]

At 2:15 AM +0200 5/27/05, Malte Brill wrote:
>thanks for your reply, I really appreciate it. As I´m not a native 
>speaker I wondered what makes an index an index, as we use the same 
>word for table of contents. I was pretty sure that there is a 
>difference and you proofed me right.

A table of contents and an index are similar because they're both 
methods of finding information. Both are "lists of topics". The 
difference is that a table of contents is a list of chapters (or 
major topics) in some logical order, which is the same as the order 
in the book (if you are indexing a book). The index is a list of 
terms that exist in the book, in alphabetical order. Indexes are 
generally a lot longer than a ToC.

If you want to get an overall idea of the book's structure, or if you 
want to find out which chapter talks about a topic, you would use the 
ToC. If you want to find out the exact place(s) where some particular 
idea or term is explained, you'd use the index.

The main difference of course is that the ToC is in front of the book 
and the index is at the back. ;-)


>When do you think an index like you described is needed for a 
>tutorial? Only if it is really big or already if there are only a 
>few (less than 100 A4 pages) of text?

A 100-page book probably needs an index - that's large enough that 
the reader can use the additional ability to find specific items.


>How would one solve that problem technically in a stack?
>
>My shot in the dark would be something like this:
>
>1.) Have a table of contents field. (preferred scrolling list field)
>      Each line of the field pointing to a card.
>2.) Have search strings delimited by comma or other char after a tab.
>      Tabstops set as high that the second item is not displayed in the field.
>3.) have an input field for the search string
>4.) filter lines of Toc field with "*"&tab&"*"&searchstring&"*"
>
>Would something in these lines work?

That's one approach. How well it works, depends on how much text 
there is on each card, as well as how complicated each card is.

But you should keep in mind, that one benefit of an index is the 
ability to glance at a total list of terms, to help orient the 
reader. And it sounds like the solution you propose would not offer 
that. It operates more like a search, I think, and the user will 
think of it as a search.

An electronic index equivalent might be a scrolling list of index 
terms - so the user can scan the list easily and see what is there - 
with one or more card names next to each index term. Then you click a 
card name to go there.

If the card text is lengthy, it would be good also to automatically 
scroll the card's field to show the particular reference, and to 
highlight it, but this is starting to require complicated code which 
you might prefer to avoid. If the card's text is short and there are 
no scrolling fields, this sort of thing isn't needed.
-- 
jeanne a. e. devoto ~ revolution at jaedworks.com
http://www.jaedworks.com