Indexes

Compiling indexes must be one of the least-missed aspects of traditional document writing. It's the sort of thing a professor might get a grad student to do in order to break his spirit.

Nowadays we don't need to do the actual sorting and compilation, and in an environment that promotes re-use, we can make bits of content automatically produce consistent index entries. So far so good!

But as I've been going along I've realised I missed an important aspect of index writing: index entries are not tags.

Having previously used any excuse to avoid compiling an index, and as a child (or at least cousin) of Web 2.0, I hadn't really understood what they were about, and gaily added generic index terms to my topics, such as "security".

This led to my index looking like this:

security,10
security,10
security,11
security,12
security,15
security,21
security,22
security,46

No worries, I thought, I can get the style sheet to bunch up all the duplicate entries and produce something more index-like:

security,10,11,12,15,21,22,46

I've seen this in lots of books, so it must be okay, yes?

Trouble is, it's really unusable. If I look up "security" in the index, I then have to visit 8 places throughout the document to see if that page happens to mention it in the way I need. What would be better would be to provide more context:

security, 10
security, policy, 10
security, over the network, 11
and so on.

An index is used like a search engine, and since it's not interactive, such a search engine must able to tell you in advance which queries are the "good" ones, where a query is only good if it narrows down the results to just one.

After you've disambiguated everything, then, you can start bunching up entries:

security, 10; policy, 10; over the network, 11,...

This approach clearly needs to be applied throughout the topic base, so now I'm considering doing an audit of the whole thing to see which index entries are duplicated and disambiguating them - since I don't know in advance which entries are going in which document.


The exercise of writing good index entries is also helpful when writing topics, as it forces you to really think about what this topic is about, and how it distinguishes itself from all the other topics in the repository.