review of indexing best practices

["Grosso, Paul" <pgrosso@ptc.com>]

Here is my review of the indexing best practices document at
http://www.oasis-open.org/committees/download.php/20479/092606%20Best%20
Practice%20for%20Indexing%20DITA%20topics_jth.doc


Example 2 is too confusing with "topic-based authoring"
being used at the text for both a primary and secondary
term.

I disagree with the suggestion made in example 4 in
that I would strongly council that the indexterm for
a section not precede the title of the section (if any).
Putting the indexterm before the title makes it harder
visually when reading the source and can affect some
structured editors' attempt to make "bookmarks" or
dynamic "tables of contents".  I would either change
this example to replace "section" with something else
that cannot take a title or to add a "title" to this
example and show the indexterm following (or within)
the title element.

Both examples 3 and 4 (as well as example 2) seem to me 
to be examples of:

  Insert block-level index tags immediately following the
  start tag of the applicable containing block element.

They do not seem to me to be appropriate examples of:

  Insert a sentence-level index tag immediately preceding
  the sentence in which the text occurs.

Example 5 says it shows a definition list item, but it
doesn't.  Instead it shows a <dd> element.  Regardless,
it shows the <dd> in the midde of text which is not valid.
(Neither would a definition list item be valid in the
middle of text.)  We shouldn't show examples that are
clearly invalid DITA.

Furthermore, even if example 5 were valid, it would seem
more suited to be an example of:

  Insert block-level index tags immediately following the
  start tag of the applicable containing block element.

than what it's supposed to be which is:

  Insert word or phrase-level index tag immediately
  preceding the text to which it applies. 

Example 6 doesn't really do a good job of motivating
or explaining what it's supposed to, which is:

  Avoid relocating an index tag within a text that has
  not changed since the last translation when you have
  pointed to a specific word or phrase in the text. 

but I'm not sure how best to create such an example
without also showing what it looked like the last time
there was a translation.

paul