Do you recall literature textbooks from your school days? Hefty and laden with discoveries? Across all language text books, one common thing was the chapter-end exercises, of course, but also the list of meanings right after the end of the lesson.

Such literature often contained complex, period-specific wording choices that spun our heads. So the meanings lists made the text accessible and easy to understand. They remained a steady, reliable source that helped me decipher the text with relative context and simplicity.

As I grew older, I found such lists everywhere. Think of dictionaries, directories, end-notes, citations, and glossaries. Diverse as they are, they served a singular purpose:

They were simple, concise, one-stop lists and acted as excellent references.

In a documentation context, such lists are arranged as a glossary: a list of terminologies simplified using contextual explanations.

Does Anybody Read Glossaries?

I’ll admit: going through the meanings solely wasn’t so fun. Glossaries are used less for reading and are more commonly used to take references and immediate help. When you notice an unfamiliar word, you try to remove that uncertainty with some help.

A vintage glossary page

Consider Razorpay Docs, our documentation platform. We host countless articles and media about multiple Razorpay products, spanning across countries and industries, containing complex application and code integrations to industry-specific business finance management.

The scope for technical jargon is vast. While we make our documentation accessible, it’s critical to balance the document’s intent with the audience. Even if we tried simplifying the language, we would still face problems. For example:

‘Bookkeeping’ is specific to accounting. Any mention may confuse the reader, but we cannot switch it to something simpler for non-accounting audiences.
Razorpay’s products commonly use ‘merchant’ and ‘businesses’ interchangeably, although they may not mean the same thing as in a dictionary.
‘Authorisation’ can mean two different things when considering it for API or bank transfer authorisation.

So how do we bridge this gap? With a Glossary! Often users come across a foreign term but do not need a detailed process explanation at that moment. Glossaries fit this spot: they are brief and straightforward, offer the necessary information based on the context and provide timely help.

Razorpay Docs Payments’ glossary page

Why (Else) Glossaries?

There is a strong business case, internally and externally, to adopt and maintain one or more glossaries.

Creates Consistency

For both the organisation and the customer, a glossary ensures the standardisation of content and that we put out industry-par content. Bookkeeping means the same on any page of your documentation.

Effective Internal Collaboration

Keeping the above point in mind, maintaining a glossary helps teams communicate better internally, externally and cross-functionally, due to its centralised nature.

Think of support functions that refer to the glossary while interacting with end users, and organisations that create company-specific glossaries for daily use. Glossaries are used to onboard new employees too.

For example, ‘Contact’ within Razorpay refers to a business product within the banking suite. We maintain a glossary for internal and external teams to understand that Contact, in this context, is a product offering.

Enhances Understanding

Glossaries simplify complex terminology. Users find relevant and timely information that improves their understanding. As such, Glossary writers undertake thorough research to keep the content up-to-date.

Improves Brand Image

All of the above points highlight how adding a glossary can make an organisation more accountable and thorough with its services. Such practices solidify reliability, which improves customers’ trust in your services.

How to Write a Glossary?

Glossaries are fun to create. Whether we are creating a stand-alone glossary or multiple of them, some instructions we follow are:

Identify Terms

We follow the following ways to identify a glossary term:

Common, recurring and relevant terms.
Frequency within the same document.
Frequency in multiple documents.

First, glossaries must contain explanations for recurring and commonly used terminology. If your document uses an abbreviation or a term that repeats multiple times, consider defining it in the glossary. Providing universally accepted definitions of the industry-specific terms is wise.

Also, consider the frequency of these terms within the same document and outside of it. Some words continually appear within the document but are negligible outside that topic. A few others contribute significantly to explaining critical processes irrelevant to where they are originally used.

Say, for example, industry terms like NEFT, RTGS, and IMPS have found a place in the RazorpayX Glossary. These terms are sparsely used but are critical to understanding RazorpayX’s offerings.

Due to their contextual relevance over frequency, we have included them in the glossary, which makes the user journey seamless. They would need to refer to the glossary instead of having to put in the effort and Google their meanings. Glossaries present all relevant definitions in one place.

Create Style Guides

By nature, glossaries are meant for reference rather than reading. Writers thus prioritise brevity and use simple but relevant terminology to define complex terms.

Undertake target audience research to develop a writing guide and adopt the technology and design to present that information.

Get Started

Start creating a repository of definitions on your platform and interlink these definitions wherever they are used in the documents. This can be daunting to start from scratch, but it pays off.

Once you have built the glossary, you must also invest in maintaining it. Update and revise the glossary regularly to include every new feature or product the organisation rolls out and the changes in the industry. FinTech, which did not exist in the dictionaries a decade back, has become a buzzword and prominent in the current times.

To Summarise

Glossaries are an essential part of your content strategy. It makes your content easier to comprehend, consistent, and accessible. Users are looking for precise information, and a glossary brings the content creators and audiences on the same page.

Glossaries serve as a bridge between two ends, a perfect balance—as are most things in life best enjoyed.

References: