RE: Glossary issues for discussion

["Johnson, Bob" <bjohnson@janacorp.com>]

My thoughts inline.

 

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf Of Dawn Stevens
Sent: Wednesday, November 1, 2023 12:43 PM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] Glossary issues for discussion

 

Caution! This email originated outside of JANACORP. Please do not open attachments or click links from an unknown or suspicious origin. If you are unsure please contact JANA IT support @ support@janacorp.com.

Hi all,

I am preparing the glossary section of the technical content specification for review. After meeting with Kris, we decided that some important questions should be discussed before sending it out for review. Here are the questions that we will discuss in our next meeting:

 

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 staets that the glossterm is preferred and an alternate would be an allowed term.

 

RLJII: I think it makes sense for glossterm to be a term of any status, with glosstatus indicating whether a term is preferred, an alternative, or prohibited. I’ve seen cases where terms of all three statuses were in use.

 

I’m not sure what “primary” would mean in this situation. I think “preferred”, “alternative”, and “prohibited” are more clear and meaningful. The practice I would recommend is defining each term, and using glosstatus to indicate preferred, alternative, or prohibited.

 

 

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?

 

RLJII: One definition per topic makes sense to me. I have seen cases where the same word was used to mean different things (for example, in different subsystems of the same product). I think it is cleaner to have one definition per topic and allow multiple instances of the same term in different topics. I think it would be a matter of practice to indicate the different sense where the same term is used in different senses.  For example, something like this:

 

<glossentry id=”security_state”>

               <glossterm> state (security)</glossterm>

               <glossdef> The state of the user in the security system, such as active, inactive, administrative.</glossdef>

</glosentry>

<glossentry id=”workflow_state”>

               <glossterm> state (workflow)</glossterm>

               <glossdef> The state of the item in the business process .</glossdef>

</glossentry>

 

Leaving this sorting to the processor seems to me to create more problems than it solves.

 

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.

 

RJII: I agree with Scott. The available parts of speech are limited and pretty well known. A defined set of values make sense. I’m having a hard time seeing where changing it from an attribute to text content adds value to most users.

 

In my experience, most glossary terms are nouns, in a few cases terms are verbs or adjectives. Keeping noun as the default seems to fit the most common use case.

 

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

 

RLJII: I originally thought the distinction was pretty clear, but as I have thought about it, it is becoming less clear. This item needs more discussion.

 

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

 

RLJII: I think keeping an image separate from the text definition makes more sense. The image serves as an example or visual illustration and can be rendered differently. For example, my equipment customers might need an illustration of different subtypes of parts or systems, such as belt conveyors versus roller conveyors, or even different types of roller conveyors (simple rollers versus rotating balls). On a medical device, different symbols might indicate different stages of device preparation or usage or treatment phase, or patient status. An illustration of the symbol in the glossary would be informative to the user.

 

 

 

Looking forward to hearing your thoughts.

 

Dawn