Search results

DITA: Glossary terms and acronyms

by Tom Johnson on Dec 4, 2014
categories: dita

DITA Glossary terms and acronymsOne 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!).

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.