← Prev in month ← Prev in thread
Next in thread → Next in month →

review of indexing best practices

From
Oaul Frosso
Date
2006-11-20T19:57:00+00:00
ID
Thread
review of indexing best practices
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
  element.
Regardless, it shows the 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
← Prev in month ← Prev in thread
Next in thread → Next in month →