Re: [dita] Practical question - indexing elements in the language reference

[Eliot Kimber <ekimber@contrext.com>]

I think the existing A-Z navigation lists in the language reference are
sufficient to enable finding of element types by name.

It would be nice to have a mapping of element names, listed
alphabetically, to the vocabulary module they are defined in. That could
be done in the index but might be more useful as a simple table or even a
reltable now that I think about it.

I agree that simply having an index entry for each reference topic by
element type name is not useful--you wouldn't normally index a reference
manual that way for the simple reason that you already have sufficient
navigation aids (either because it's organized alphabetically or because
you provide types of navigation lists we already provide).

I also don't think it's realistic to try to index every mention of a given
element type in the arch spec--if we want that we can generate those index
entries from the existing <xmlelem> markup to produce a simple list of
page numbers where a given element type is mentioned. But I'm not sure
that's useful.

I'm also not sure it's useful to index mentions of elements under a
primary entry for that element type because for some elements that would
be a large number of hard-formulate index entries. For topicref, basically
any subject related to maps will have scads of mentions of topicref, most
of which are not that useful to index.

Not sure this helps formulate any cogent policy.

Cheers,

E.

----
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com




On 7/9/15, 12:29 PM, "Robert D Anderson" <dita@lists.oasis-open.org on
behalf of robander@us.ibm.com> wrote:

>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/)