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
