DITA: Glossary terms and acronyms

by Tom Johnson on Dec 4, 2014
categories: dita

One of my colleagues was asking about best practices with glossary terms and acronyms in DITA today, and I realized that this is a pretty confusing aspect of DITA. I spent a good chunk of time trying to sort it out and outline best practices. I added a topic to my DITA QRG called Acronyms and glossary terms.

Overall, I think glossaries are underused in help material. We become numb to our own jargon, which makes help material much more difficult to understand. But aren't words the building blocks of communication. If we start with fuzzy words, how can we expect to articulate concepts clearly? Creating a glossary should be tech writing 101 in any user guide.

At the same time, there are many terms that are necessarily abbreviated for communication to be efficient. If each time you had to start off a DITA post by explaining what DITA is, you'd never get anywhere. David Gash makes a joke about this in an article on conditional processing in DITA:

What Is DITA?
Just kidding! Every DITA-related article in the world seems to start with this section, whether it's needed or not. I'm pretty sure that if you don't know what DITA is, you aren't even reading this article. Movin' on.

I agree -- you have to draw the line somewhere. At the same time, I've seen a lot of annoyed readers who complain that DITA is never defined. Or they attend a presentation on APIs and are aghast that the term API is never defined. Well, a good glossary can solve this problem in a user guide. One little link to an unfamiliar term allows you to clear up its meaning without forcing you to take an explanatory detour each time.

One neat thing about DITA's glossary type is that you can set it so the word's first appearance on a page is a full term, and subsequent appearances of the term appear as acronyms. In my article, I show the difference between using abbreviated-form and term, and how to consolidate glossary terms in your ditamap.

For example, you can set the surfaceFormTerm to be "Darwin Information Typing Architecture (DITA)" and subsequent terms to appear as "DITA" -- this is assuming that you actually want to link the same glossary term multiple times on the same page. (I best most would say once is enough.)

I'd appreciate any feedback about best practices with glossaries and acronyms in DITA. I assume most people are pro-glossary but most of us are too lazy to create them. One of my goals is to be more diligent and aware of glossary terms and acronyms in my help material.

To read my best practices, see Acronyms and glossary terms in my DITA QRG (hey, another acronym!).