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.
[SH] I think we need to continue to provide options for Aliases (glossAlternateFor covers this). I don’t think that glossterms should only be primary/preferred. If you provide a glossAlternateFor link from
term A to term B and neither state that they are the preferred term, how should we handle it? They both can’t be the preferred term, right?
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?
[SH] No. I think we should provide the option for multiple definitions. We had that use case at Jeppesen, though it’s been too long for me to recall a specific example. I do think there is a use case for multiple,
numbered definitions.
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.
[SH] There is a limited set of Parts of Speech, so I don’t know why we’d want to have it contain text. A prescribed list cuts down on potential errors or typos that could affect processing. glossProperty is
generic, so needs to be flexible for unanticipated values. I’m sure there could be company-specific properties that would have their own custom processing to handle them.
4 –. What is the distinction between glossUsage and glossScopeNote?
[SH] IMO, glossUsage is the anticipated / expected use of the term in content. glossScopeNote describes the types or volumes of content that this term covers. I think they cover different aspects of the term
that are important to keep distinct.
5 – why would you put an image in glossSymbol rather than just embedding it in the glossdef?
[SH] I think the glossSymbol is for an image associated with the term, but it is not, in itself, a definition of the term. I think it’s akin to an example of the term. Perhaps that is something that is missing,
or perhaps we could get rid of glossSymbol in favor of allowing the generic <example> element?
Looking forward to hearing your thoughts.
Dawn