Why and how to create, validate and maintain glossary throughout the project?

When I start working on a new project I usually start with learning about the client’s domain. I try to identify the major players on their market and learn who their customers are. This gives me a better understanding when we are talking about business needs and requirements. Despite all these preparations in the first few weeks I often feel stakeholders are speaking a different language. It is usually not just because they are talking about hot topics, tasks and issues which I am not familiar with, but also because they use abbreviations and terms I don’t know or have totally different meaning for me.

I have found it very useful to create and maintain a glossary from day one which helps me get up to speed without having to ask clients to explain me a particular term / abbreviation too many times.

Another reason to put together a glossary is that in some cases people have different understanding of the same term / abbreviation. By having a glossary you can avoid (or at least reduce) this kind of ambiguity and confusion.

Third reason is when you create reports which include terms and abbreviations you need to be careful. Business people tend to export these reports into Excel and circulate them in e-mails. Having terms and abbreviations defined, available and being used means decision makers are more likely to interpret figures on the right way, even if they are not familiar with the report they just received with a red flag. That is why I think it is a good idea to include somehow or relate to these definitions in all reports.

What a glossary should contain?

Start with the term / abbreviation you are defining. In case it has got multiple widely used aliases capture those too. Try to explain terms as simply as you can and if possible do not refer to another term / abbreviation. Complex glossaries with cross-references are harder to read and maintain.

When you ask for a definition some people are better in explaining than others, but if you ask for examples these always help to check whether you are on the same page or not. I am pragmatic so I prefer practical examples over abstract definitions and what is more practical than a real life example?

Glossary Template

To help you getting started I created an Excel template which you can download.

Feel free to use it as is or tailor it so it will suit you better.

OK, I created my glossary. Am I finished?

No. Before you finish you need to validate that your definitions are correct and clear. Try to get some feedback from stakeholders and project team members. If there is any discrepancy try to resolve it. It can happen that during this exercise you uncover misunderstandings. If that happens take the opportunity and fix these.

Publish it

A glossary kept in your drawer doesn’t make a difference. Make sure all stakeholders are aware of it and your team also has access to it. If everyone working on the project use common terminology it can reduce number of misunderstanding and help communicate better with each other.

Finally, it does worth to review it on a regular basis and add any missing or new items. If you keep it up to date then it could be a great guidance for newcomers.

Do you think I missed something? Do you have your own template which you want to share? Do you have a story to be told when a glossary helped you? Leave a comment or contact me.