Glossaries are not Instruction Manuals

ESTIMATED READING TIME: 3 MINUTES

We were recently helping a small definition writing team at one of our client sites get a handle on writing some tricky definitions.

In the course of the conversation, these two important questions arose:

• Should they include in their glossary each of the chemicals they use as part of their core business?
• Should those definitions outline the specifications for the use of those chemicals, because this information is so vital to get right?

Our general rule of thumb when determining what should be added to a glossary is, if the term is central to business process or information or is needed by the definition of other terms, include it.

But these kinds of generic terms (by which I mean, terms that will have precisely the same definition across all industries and businesses) fall into a unique category.

To include or not to include

The argument for including them is that, because they’re so central, people across the business may need to know what they are and how they’re used or what they’re used for. There may also be reporting that includes these terms.

An argument could also be made that these chemicals are core assets, as this client couldn’t perform their business without them. And we are helping this client specifically with defining terms associated with the company’s operational assets.

On the other hand, because only specialist staff actually use the chemicals, staff who don’t have a thorough knowledge of the use, storage, mixing and safe handling rules associated with the chemicals should never need to use that kind of information. And we are not in the business of replacing hazardous chemical information systems!

As one of their team pointed out, if we’re relying on the glossary definition as an instruction manual for our chemical use, we’re in trouble.

But the question of whether they needed representation in the glossary remained. Would it be useful, or allow for more effective communication, if these terms were included?

When glossaries mutate into instruction manuals

While there are some good arguments for including the chemicals in the glossary, the instruction information is a different thing.

Our goal, when writing definitions, is always to make them as short as possible while still conveying the information necessary for readers to identify exactly what this term refers to in the real world.

Specificity and succinctness in balance is what we’re after.

Weighing your definitions down with unnecessary details, even if those details are important, even vitally so, to the activities referred to by the term, or that the term is involved in, leaves your glossary feeling unwieldy and impractical. It won’t get used.

The bottom line is, your glossary isn’t an instruction manual. Functional areas should have all the necessary documentation for successful operation in manuals specifically written for this purpose.

Enabling your glossary to enhance operations manual usage

Our solution in cases like this gives easy access to operations manuals, but also keeps term definitions as short and clear as possible.

Firstly, we suggest including the chemical names in the glossary but not writing new definitions. Simply use the standard dictionary definitions, or industry definitions. Thankfully, our client is using the Intralign Encyclopaedia to establish and house their glossary, and importing directly from the WordNet dictionary can happen easily within the platform. This makes including these terms fast and efficient.

Next, we suggest identifying the relevant operation manuals and ensuring the manuals have a staff member who is accountable for reviewing their currency and accuracy.

These manuals are then registered in the Intralign artefact register, which is part of the encyclopaedia. Links are set up between the chemicals listed in the glossary and the operations manuals that refer to them.

When staff members need the operations manuals, they will search for the chemical in the glossary. From there, they can review all artefacts (the operations manuals) linked to that term and get the link to where the document is stored in the business’s document management system.

This approach allows for a thoroughly comprehensive glossary—a business encyclopaedia—that enables easy finding and accessing of current operations information and avoids lengthy definitions or comments associated with terms in the glossary.

Everyone’s a winner.

Join the discussion on LinkedIn