Summary of glossary questions

We’ve had several discussions about the glossary specialization. I want to attempt to summarize the points. We started with an e-mail from Dawn Stevens on 01 November 2023: https://lists.oasis-open.org/archives/dita/202311/msg00001.html

Amber Swope will be joining us tomorrow, and I encourage TC members to prep for the call. Everyone had an action item to do the following:

Read through the “Glossary entry elements” section in draft #17 of the DITA for Technical Content 2.0 draft specification
Read the following white papers:

DITA 1.2 Glossary and Terminology Specialization Feature Description, Kara Warburton (October 2009)
DITA 1.2 Feature Description: Improved glossary and terminology handling, Tony Self ( December 2009)

Below are the questions that Dawn raised, annotated with information from DITA TC minutes or the white papers:

1 – What are we defining? The term that appears in glossTerm is what?

Is it just a term of any status?
Is it a primary term?
Is it a preferred term?

Terminology is inconsistent throughout, but seems to imply the word is either primary or preferred. Is there a distinction between these two adjectives? And do we agree that glossterms should only be primary/preferred. What about using DITA to create a glossary for translators who need to know these other terms perhaps that are not primary or preferred? Consider glossAlternateFor which is an xref to another term – there is an implication that one term is preferred over the other. The way the description is written the alternate would be less desireable than the “preferred” term in the glossterm. Furhter, the glossStatus element allows me to set a value or something like prohibited – why would I do that is the glossterm was always the preferred term? If not specified, glossStatus states that the glossterm is preferred and an alternate would be an allowed term.

<eberlein>The Warburton white paper has the following text on page 14 (emphasis added):
‘In technical writing, synonyms and variants should be used judiciously and often avoided altogether. The use of one term consistently to express a given concept is preferred so that communication is clear and so that translation costs are minimized. For this reason, when synonyms and variants do exist in popular usage, it is common practice in commercial environments to choose one of the terms as the “preferred term.” ‘
<eberlein>

2 – Are we agreed that one glossentry topic includes only one definition – one single sense of the term. Is that too prescriptive? Couldn’t a company choose to create a dictionary that would include perhaps numbered definitions?

<eberlein>We’ve discussed this several times now: 07 November and 28 November. </eberlein>

3 – glossPartOfSpeech is defined by the @value attribute. However, if used, it is presumably translatable content. Should this element be modified to contain text instead? If we keep it as an attribute – why is noun the default? Does there need to be a default? glossProperty has a similar problem, but is open-ended so we don’t know how these properties might be used and whether they would be translatable.

<eberlein>Discussed at the 07 November meeting. Consensus that folks should use a subject scheme map to control the values, and that the values should not be translated.</eberlein>

4 –. What is the distinction between glossUsage and glossScopeNote?

<eberlein>Discussed at the 07 November meeting. Folks suggested the following:

Leroy; could glossScopeNote be more general? glossScopeNote is maybe only allowed in glossbody, but glossUsage is allowed in other places.
Frank; from my analysis, it's about usage; glossUsage is how to use the term, glossScopeNote is where to use it.

The Warburton white paper summarizes what the elements were intended to do in the following ways:

<glossScopeNote: A clarification of the sense designated by the terms such as examples of included or excluded companies or products.

<glossUsage>: Information about how the term is used in context.

The Self white paper summarizes what the elements were intended to do in the following ways:

<glossScopeNote>: Information on what the term does or does not apply to. Categorized as “Notes on scope of usage”.
<glossUsage>: Supplementary information explaining the correct use of the term. Categorized as “Correct usage of term.”

</eberlein>

5 – why would you put an image in glossSymbol rather than just embedding it in the glossdef?

<eberlein>Discussed at the 07 November meeting.</eberlein>

Kristen James Eberlein

Content Engineer | Health Education & Content Services | 507-293-0006 | eberlein.kristen@mayo.edu

My pronouns are she/her/hers.

dita message