Bitesize DITA: Glossaries 101

Almost all the content we write contains some kind of jargon – terminology unique to our domain, industry or even just to our own business. That sounds like a bad thing, but without common shorthand, communication would grind to a halt – for example every Bite-sized DITA article would have to begin with a definition of DITA, topics, maps and so on.

Glossaries are a useful tool – a way of making sure readers can access definitions of specialist terms without having to keep repeating it throughout a publication. But without structured authoring they can be hard to develop and maintain. Just keeping content properly alphabetized and maintaining cross references between terms and definitions can be arduous and error-prone. DITA gives us some powerful tools to be able to offer the reader useful glossaries that are straightforward to write and maintain.

The basic syntax of a glossary is a pairing of the term, <glossterm>, and the definition <glossdef> inside a <glossentry> element. For example:glos1

You can add multiple <glossentry> elements to a map as glossrefs, but you can also store multiple glossentries in a single <glossgroup> topic – which can be a more convenient way of authoring if you have many glossary terms and definition to write.

But glossaries in DITA give us much more than a way to pair terms and definitions. By using keys, we can create automatic links in the output between keywords (terms) and their definition:glos4

To create this effect, each of the highlighted terms are listed as keys in the glossary map:glos2

You can then connect keywords in the text to their respective glossary topics using keywords with the @keyref attribute set to the appropriate keydef.glos3

In the next BiteSize DITA we will look at some more sophisticated ways to use glossary terms and definitions such as acronyms, synonyms and preferred terms.

View more Bitesize DITA tips, tricks and insights

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