Introduction

“A wise one writes it down, a foolish one memorizes it.” (sr. “паметан пише, будала памти”) – A Serbian proverb

Let’s admit it - the biggest enemy of a software project’s success is ambiguity. Ambiguity of requirements (am I solving the right problem?), ambiguity of the system design (am I changing things in the right place?), ambiguity in code abstractions (wtf does this thing do?) etc. Anything you can do to reduce ambiguity can only help a project in the long run.

Humans have a very limited working memory. Less things we have to keep in our memory, higher the chance we’ll make the right decision. And what we can’t keep in memory, it should be only a search away, without the need for breaking ours, or anyone else’s flow.

The trouble is, with Agile methodologies becoming the default, documenting things is rarely a priority. There’s no place you can go and quickly learn what you need. Or there is, but it isn’t up to date, or it’s scattered among dozens of Slack channels, private chats, Miro boards and whatnot. Important information lives in people’s heads. If you don’t understand something, the first thing you’ll do is to find out who knows what you need, and then go ahead and ask that person. A new hire comes and does the same things like you. Wasted time just keeps adding up. Also, people leave companies, and important information leaves with them, hurting the project (at least until someone else learns the same information in the same way, which means more wasted time).

Most developers don’t like writing technical documentation, and it seems that project/product managers don’t like writing project documentation either. They just focus on writing user stories, meeting OKR-s and etc., none of which contributes in having an overall picture on what is being solved, how and why. What can make things even worse is when those managers get promoted from another role, not because they have demonstrated a vast domain knowledge or managerial qualities, but because of belief that they’ll perform better than in their current role.

With a domain knowledge taken so lightly, no wonder why wrong features get developed, same thing gets done multiple times, solutions get overengineered and many other problems. Also, arguing with someone for hours about something just to figure out that you have a completely different interpretation of what that something means is because there is no single source of truth about that something. All of this drives disinterest into project’s success and an employee burn-out.

A glossary of terms…

One way to reduce ambiguity is to keep everyone on the same page, both current and the future colleagues, when things are being discussed or worked on. Having a glossary of terms used in the project is a great way to do so. For example, if the project is in the e-commerce domain, a glossary should say what an order is. If an order has a status, every status should be described, how it affects an order and so on. Product types, all of the abbreviations used etc.

A glossary of terms could correspond to the ubiquitous language described in the Domain-Driven Design, that is, a list of unambiguous terms shared by domain experts, users, and developers (note that I’m not advocating DDD here, it’s just that having a common language is universally a good idea).

This is not a novel idea, it’s just forgotten or simply ignored.

Here’s Rich Hickey, one of my favorite people in this industry, explaining why having a project glossary (I recommend the entire video though):

Or, see here and here what makes a project glossary.

…defined in the source code

If the project documentation isn’t exactly a “first class citizen” on the project you’re working on, this is a good, alternative place to maintain a glossary. Why? It will live right with the rest of the project files and be available to all developers, right from the editor. It’s versioned, and changes to terminology can be committed together with implementation changes.

You’re probably asking yourself now - how does this help at all, since it’s available only to developers? As I’ve said earlier, it’s important for developers to know what they’re dealing with in order to execute properly. If no one else cares, then there’s no point in maintaining a page in Notion that no one will ever read or update. Maintaining the file will help everyone in the development team, and also help reduce the onboarding time of the new hires.

How to make one?

Chances are, you have an up to date README.md file that explains how to set up the project. You can create an additional file, say glossary.md and highlight in the README that this is the file to refer to for the project terminology. It can follow a simple format, like this:

# Glossary

## Term 1

Definition of the Term 1. Deprecated, see [Term 2](#term-2)

## Term 2

Definition of the Term 2

and so on. Markdown files are easy to read and update, even without rendering into HTML. If you use VS Code, you can use extensions like Markdown sort to maintain the order of the terms, or Markdown Full Text Search for easier search in case of larger files.

Conclusion

So the next time when someone on the project clarifies some term over Slack, MS Teams, e-mail, meeting notes or whatever, make sure to grab the text immediately and put it in the glossary file to persist it, don’t just memorize it. Once recorded, insist on that definition in further communication until there is a compelling reason for change.