Re: [docbook-apps] Indexing.

[Thomas Schraitle <tom_schr@web.de>]

Hi Dave,

Am Samstag, 5. Mai 2012, 08:10:05 schrieb davep:
> I'm about to start indexing a db5 book.
> Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has
> been there and done that, got the tee-shirt and found the pitfalls in
> docbook?

I don't know this author, so I can only speak about the experiences of 
indexing my book.


> Any advice from those with lots of experience of using
> db indexes please?

Are you asking more about the indexing task itself or about the technical 
aspect?

Speaking about the indexing task itself, IHMO this is something that some 
books don't take it seriously enough. An index is a service to make the book 
more accessible to readers. I've seen lots of bad index which came just as an 
alibi, but with no value.
So it isn't a surprise that a good index takes time and energy. When I've 
created the index of my book, it took lots of iterations and I guess it still 
isn't perfect. :)

What I've learned is this: don't write and create the index simultaneously. It 
doesn't work (well, at least for me). Try to finish your book and when it's in 
a decent state, then and only then, focus on the index. If you don't have an 
idea what to index, look at other books. I've found O'Reilly books has mostly 
good indices.

A good index should contain different "access paths". For example, if you want 
to know something about namespaces in DocBook you can look it up as 
"Namespaces > DocBook" or "DocBook > Namespaces". IMHO both are valid and 
needed. Apart from this, try to be consistent. Either plural or singular, but 
noth both. I preferred the plural form.


If you are more interested in the technical aspect, that depends (heavily) on 
your document. I assume, you write more technical documents, right? In that 
case, you can automate (some) things to make the indexing more easy.

For example, if you write about HTML5 you will probably use <tag> or 
<sgmltag>. If you use this tag consistently, you can add some of them 
(semi-)automatically to your index page through profiling. I've described this 
topic in my book:

 http://doccookbook.sf.net/html/en/dbc.structure.adding-indexterms.html

With the help of profiling, this eases the pain of indexing and you can 
concentrate on the more difficult parts that can't be automated.

Hope that helps and good luck with your index. :-)

-- 
Gruß/Regards
  Thomas Schraitle