Bitesize DITA: Glossaries: a closer look

Last time we looked at basic glossaries and why they are useful, so let’s move on and explore some of the more advanced capabilities that DITA offers.

We can break down the <glossentry> topic into three main parts:

  • <glossterm> : the term itself
  • <glossdef>: the definition to be paired with the term
  • <glossbody>: supporting information about the definition

<glossbody> is a container for a variety of useful elements that you may want to include in your glossary. Here are a few examples:

Variant terms

Within <glossBody>, the <glossAlt> element is used to define any alternative to the term being defined. For example if your main term is Unidentified Flying Object you may want to include the acronym UFO and the colloquial term Flying Saucer.  Each variant term needs its own <glossAlt> element which can then contain further semantic detail about the kind of variant it is. For example:

unidentified flying object

Other variant terms include:

  • Abbreviation <glossAbbreviation> :for example Capt. is an abbreviation of Captain
  • Short form <glossShortForm> : for example The Web is a short form of The World Wide Web
  • Alternate for <glossAlternateFor>: for example post-it  is an alternate word for sticky note

If you’re also using keys in your glossary map, you can link the full or abbreviated terms to the glossary entry and it will automatically resolve to the right definition.

Parts of speech and usage

You can define the grammatical part of speech of a glossary term,for example: <glossPartOfSpeech value=”noun”/>

The <glossPartOfSpeech> element lives inside the <glossbody> element and refers only to the primary term (so you cannot define separate parts of speech for each variant term)

You can also add information about the usage of a particular term, for example if it is a colloquialism, or if the usage is obsolete.

The @value attribute of the PartOfSpeech element is free text rather rather than a closed list, so, as with many DITA attributes, there needs to be consensus within your team to ensure that everyone is using the attribute consistently.

Glossaries and Taxonomy

If you think that variant terms sound like the kind of thing that belongs in a taxonomy you would be right – there is an overlap between glossaries and taxonomies.  As your glossary grows and develops, there may be a point at which it could usefully form the basis of a more formal taxonomy and you may want to think about investing in taxonomy tools or using the taxonomy features in your CCMS if you have one.  Conversely, if you are considering building a glossary, it is worth checking whether there is an existing taxonomy that you can reuse. As with so many other aspects of DITA, advance planning and consideration of the purpose of the content saves duplication of effort in the future.  

View more Bitesize DITA tips, tricks and insights

If you have a question or a useful tip to share, why not tweet us @BiteSizeDITA

DITA Training

Looking to develop your DITA skills? Book your place on one of our DITA training courses. Mekon offer a range of DITA training to suit your specific needs:

Our specialist training courses can be delivered as a standalone training course, or as part of an integrated, customised solution. We deliver our courses in a number of ways, here at Mekon, on site with you or remote.

Find out more