Practical question - indexing elements in the language reference

["Robert D Anderson" <robander@us.ibm.com>]

On this week's call, I mentioned the poor quality of index entries in the language reference. Elements are indexed multiple ways, with no consistent design. The all inclusive package has just over 600 elements; those topics (plus the containers) have over 2600 primary, secondary, or tertiary <indexterm> elements.

All of the following are used today:
* Primary entry with the element name (most common but not universal)
* Primary entry with natural language (add "abbreviation list" to "abbrevlist")
* Element name as secondary entry under a domain or module (we have primary "highlighting domain" with one secondary entry for each element)
* Primary entry based on purpose (we have image, alt, and longdescref all indexed with "images")
* Various other methods (<shortdesc> has entries under the primary terms "topics", "maps", "elements", "examples", "processing expectations", and "short descriptions")

In thinking about which of these are useful, I remembered Eliot's comment yesterday:
> Of course, in the ideal index, most of the terms are *not* in the titles,
> since part of the point of an index is to relate non-obvious things to
> their locations in the doc.

Every element in the langRef uses the element name as the title. Is it useful to index the element name, exactly as it appears in the TOC?

Personally I only use the index to look up architectural concepts or features. For element names, I use the TOC. In the all-inclusive package today, the conceptual terms are spread among 600+ element names and hundreds more near-identical primary entries. We could clean up primary entries by indexing elements only under the domain / module name, but that is only helpful if you already know how we group elements. It also raises the same question - is it useful for the index to reproduce exactly the same grouping already found in the TOC?

With all that in mind, I lean towards a default policy of not indexing every element topic. I suggest this as a general policy, for topics that define a single element, not an absolute rule about primary entries in the langRef. Attribute topics in the langRef need indexing. Elements with special processing expectations need indexing. Other groupings will be useful (maybe a primary entry grouping all deprecated elements). Other exceptions are expected.

Thoughts? I expect there will be at least a few on this one...

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)