RE: [dita] FW: [dita-translation] Groups - Best Practice for Indexing DITA topics.doc uploaded

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

> -----Original Message-----
> From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com] 
> Sent: Tuesday, 2006 August 29 09:59
> To: dita@lists.oasis-open.org
> Subject: [dita] FW: [dita-translation] Groups - Best Practice 
> for Indexing DITA topics.doc uploaded
> 
> 
> The document named Best Practice for Indexing DITA topics.doc has been
> submitted by Dr. JoAnn Hackos to the DITA Translation Subcommittee
> document repository.
> 
> Download Document:  
> http://www.oasis-open.org/apps/org/workgroup/dita-translation/
> download.php/19985/Best%20Practice%20for%20Indexing%20DITA%20t
> opics.doc
> 

Not to sound petty, but I'd prefer that tool names be
omitted from an OASIS sponsored best practice document.
Phrases like "tools such as Adobe Framemaker" and such
are inappropriate.  The fact is that there are many tools
that do (or can do) things "like Framemaker".  I would
hope we would plan to purge this document of such
gratuitous references before we publish it.

---

The first bullet point under Recommended Best Practices
has an unmatched close double quote and the coloring of
the example tags is inconsistent.

---

I fear that some of the examples might mislead some readers.

In particular, the omission of any page numbers in, say,
Example 2 means it isn't clear to the reader that only
leaves in nested indexterms are actually indexed.  The
wording about "two primary index terms ... and two
secondary index terms" only serves to add confusion.
In point of fact, the example does not index any
primary terms.  The only affect of the primary index 
terms is to make the secondary index terms secondary,
and there are only two index entries generated.  Perhaps
it would be clearer if the resulting index were shown as

DITA
	topic-based authoring  . . . . . . . . 15
topic-based authoring
	introduction . . . . . . . . . . . . . 15
 
At least that might help enforce the idea that there are
no primary index terms getting indexed in this example.

Similarly with the rest of the examples, though perhaps
page numbers could be omitted for the rest after a careful
explanation of this issue.

---

paul