Using Glossary in Tech Writing Team

Technical writing is a global notion. Technical documentation is written or localized all over the world in so many different spheres. Just imagine how many technical terms there are. Even if you have been a technical writer for a long time, working in one industry, it doesn’t mean that you know all the terminology of this industry by heart. And nor should you!

A simple example – software documentation. Every new feature brings new words connected to it. Or, there are terms that are just very deep and complicated so they are extremely rare to be found in a user manual. And, another thing – you are not a robot, so you can’t know/remember everything. But, as we are all aware – all terminology should be used correctly and explained properly in user manuals. This is why, a glossary is such a great idea for a technical writer.

Terms in Technical Writing

Let’s start from the very beginning. What is a term? Terms are words or expressions that acquire a specific meaning in a specific context. Moreover, these words’ meanings should be very precise within this context. Quite often, terms are connected with a particular science, technology, profession. Sometimes, one term can mean different things in different spheres. Like a word ‘degree’ in mathematics means a unit for angle measurements while in physics it is connected with temperature.

What’s important to remember here is that all terminology should be correct in technical documentation. As mistakes can lead to really serious consequences. Also, you can’t just use a term word without any reference or explanation. We have recently posted an article closely connected to this topic – Neologisms in Tech Writing. Neologisms are new words coined because of some phenomenon (like some emerging technology, for example). As you might guess, new terms can be neologisms, so, check out that article, it is quite interesting.

The golden rule to follow – even if you know the term it doesn’t mean that your readers do. And, here’s the golden rule number two (it is just equally important) – always, always check your terms. Any doubt creeps in – refer to a glossary. Sounds good, but where do you find one?

Creating a Glossary

Some companies already have glossaries. And, this is great. But, sadly, not that common. Which means that chances are high you need to create one. Of course, you can google everything or keep asking subject matter experts. This won’t take you much time to understand how convenient this is to have all terms in one place. Here are some tips on creating a glossary for tech writers:

• Items should be in the alphabetic order for easier navigation.
• If you are creating an online glossary, add links and cross references. The ability to navigate quickly between articles and resources is one of the main advantages an online glossary has, so don’t neglect it.
• Start with basic terms. Ideally, each word that can be characterized as a ‘term’ in your specific area should be on the list. Firstly, this way you’ll make sure that you do know exactly what they mean. Secondly, imagine how helpful this would be when hiring people!
• When adding rare/difficult terms, definitely consult subject matter experts.
• Make sure to keep your glossary up to date not just by adding new words, but updating the existing articles, too.
• Just a tiny advice from a person with experience: if you came up with a term to add or some addition to an article, do it right away or write it down somewhere. Otherwise you will 100% forget this 🙂

We, the ClickHelp company, have started working on our own ClickHelp Software Documentation Glossary. It is still a work in progress, but we are getting there.

Conclusion

A solid glossary for your documentation team prevents hours of Internet search from happening. It helps teach new hires, keep the whole team up to date with the overwhelming amount of new information. But, most importantly, it helps you create better, more comprehensive user manuals. If you work with such a glossary when writing documentation, you can be sure the documentation is precise and all the troublesome words are explained to readers!

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices