Re: glossaries

["Deborah Snavely" <dsnavely@xxxxxxxxxxx>]

Rick Henkel asked:
>My team lead wants a large glossary for our entire documentation suite.
She
>then wants to use the applicable parts of that glossary for smaller
>glossaries in individual manuals.
>
>My first thought was to use a custom marker for each manual, use the
entry
>text as the marker text, and automatically generate a glossary for each
>manual. We have character tags assigned to certain words in the
entries, but
>I figured I could use IXGen to easily add that formatting. But I soon
>discovered that several glossary entries are too big for the marker's
255
>character limit, especially when I added the character tag building
blocks.
>
>So then I turned my attention to cross-references. I figured a writer
could
>create a cross-reference to the master glossary for each entry he needs
in
>his manual. Because we wouldn't want the cross-references linked, we
could
>just convert them to text when the glossary is built. (But any changes
to
>the master glossary would not automatically make it into the little
>glossary.) But the character tags weren't coming through because the
>cross-reference just uses the paratext building block. So the writer
would
>still have to manually insert the character formats.
>
>I guess I have a few questions for you all:
>
>* Is there a building block I could add to the cross-reference format
that
>would bring the character tag info across?
>
>* Is there another method that would work better that I haven't thought
of
>yet?

Rick,

A couple of thoughts. It sounds to me as though you're going to bump
noses with that 255-character limit no matter what, but here's what I
know.

One is, you can set the font back to default in a marker following an
entry using a shortcut </> (I think...it's been a year and I haven't
used it since; it's in the doc somewhere, I believe.) This shortcut can
save a LOT of space in complex marker entries full of formatting. 

The other is more of a thought-starter. It's an approach that I used for
a multi-group, multi-document glossary at a previous work site. 

Our goal was to examine and normalize glossary definitions across
documents. I assembled existing source glossaries, applied different
conditional text settings to each source-book's glossary content, and
then slam-dunked the whole into a table for quick sorting, then
converted back to text. 

My work focused on eliminating duplicate as much as possible. Sometimes
you need a short definition for a user guide and a long one for a
programmer guide, but I normalized the short defs to a standard style,
expanded and cross-referenced all the acronyms, etc., etc. 

Later, when any of our writers were going to do a new version of a given
book, we'd use conditions to given them only the appropriate
glossary/ies for that book, save it to another file, delete hidden
conditionals, and give THAT file to the writer. Updates happened after
that book went to bed, in one of two ways: 
1) with limited changes, the writer sent me email of the updated entry
and text, and I updated the super-glossary; 
2) with massive changes, I treated the new final glossary as a new
glossary for incorporation into the "super-glossary," except that I need
not create a new condition for that source book.

Clearly, neither my approach nor yours is completely appropriate, but
the only thing I can think of that really is appropriate is a
glossary-as-database. And who has those kind of resources?

Deborah Snavely
Document Architect, QA & Docs, 
Aurigin Systems, Inc. http://www.aurigin.com/ 


** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **