Date: Sun, 15 Jun 2003 03:05:50 -0700 From: Murray Stokely <murray@FreeBSD.org> To: freebsd-doc@FreeBSD.org Subject: Random thoughts on indexterms.. Message-ID: <20030615100550.GA390@freebsdmall.com>
next in thread | raw e-mail | index | archive | help
I've recently pointed out to some people minor inconsistencies in the
indexterms, so I thought I'd do a little braindump in the hopes that
someone will add this to the FDP, come up with other guidelines, or
argue why these guidelines shouldn't be adopted.
* indexterms should be lower case unless the word refers to an acronym
or proper noun.
* indexterms should almost never be identical to the section title.
For example
: "<indexterm><primary>backup software and basics</primary></indexterm>"
Is a bad indexterm for several reasons. It is way too long, and not
organized properly. "backup software" is a legitamite primary index
term, but this "and basics" reads like a section title, not like an
index entry. The best I could do for this one was remove it since
it's in close proximity to other more succinct backup-related
indexterms. I don't see to many secondary indexterms like "basics" or
"details" underneath a legitimate primary indexterm as I look through
the CS books within arms reach.
* tertiary indexterms are almost always bad
* indexterms should be succinct - the index must be printed in two
column format at the back of a book. long-winded indexterms make
this impossible.
I don't like the :
<primary>network card configuration</primary>
<secondary>troubleshooting</secondary
...
<primary>network card configuration</primary>
<secondary>testing the card</secondary
entries in the config chapter which just mimic the section titles.
These are too long and they don't really read like index entries to
me.
That's it for now. More later. ;)
- Murray
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030615100550.GA390>