Re: Indexing style refs
You cannot accommodate every user however they want. At a certain point, you
must say no. If my user gets upset because I haven't put "way cook button"
in the index, or if I include 20 synonyms and they can't find it because I
didn't include the 21st one, I say tough. We're here to create solid,
accurate documentation, not to bow to every off-the-wall whim of everyone on
the face of the earth.
Sorry, John--Ms. Gallagher is exactly right.
The index should include every *reasonable* synonym for the terms you index. If you want to train the reader to use your terms (the controlled list), then list each synonym as a cross-reference to the preferred term (as in "trash collector. See sanitation engineer").
Of course, it's easy to find *unreasonable* synonyms: no one's going to look for "way cool button" in the index unless your app has a button labelled Way Cool. It's also necessary occasionally (particularly in print) to limit the size of the index, so you might have to limit the number of synonyms you include.
But the very purpose of the index is to get people to the information they need without forcing them to know your word for it, and optionally teaching them your word for it (but only as a side effect to getting them to the information they need).
HTML Indexer 4 is still the easiest way to create and maintain indexes for web sites, intranets, HTML Help, JavaHelp, and other HTML documents.
HTML Indexer 4 includes fully integrated cross-references, target frames and windows, multiple-file output, "one-step accept" of default entries, and more!
RE: RE: Indexing style refs: From: John Posada
Search our Technical Writing Archives & Magazine