#44-Maintain an Organizational Glossary

No matter what kinds of products and services an organization offers, there are terms that are specific to them.  These terms must be carefully defined and consistently updated as things change.  This podcast is all about creating such a set of definitions.

Transcript

Maintain an Organizational Glossary

Most organizations have specialized language that comes from the nature of their products, their processes, and the surrounding context they operate in.  This terminology can appear in many places: documentation, planning artifacts, in various kinds of tests, and so forth.

It is important that these terms are discretely defined, that these definitions are readily available for reference by anyone, and that there is an easy way to update them as situations change.  Also, these definitions should be in a single place, with no duplication.

There are several reasons for this, even if the terms are fairly straightforward.  For example, if something refers to me as "First name Scott, Last name Bain" while some other part of the system says "Christian name Scott, Surname Bain", this creates an inconsistency and is also a form of redundancy.  If later it is decided that a middle name or initial should also be included in a "person's name", then both places will have to be updated and, given the inconsistency, there is a danger that one will be missed.  This will become a source of hard-to-locate defects over time.

Also, the domain itself may have specific terms that come from the work being done. I once worked with a company that did pressurized pipeline management, and there were a myriad of terms that they used all the time which would not be clear immediately to someone unfamiliar with the technology.  They had an extensive glossary of these terms which helped me immensely in attempting to get up to speed and contribute.

The question is, what form should this glossary take?  We want something that is extremely readable, that can be verified at any time in terms of its accuracy and completeness, and that can be updated by anyone without requiring specialized expertise in tools or technology.

I recommend that acceptance tests be used to accomplish this.  Such tests are not written in computer code but rather using human-readable language.  The most common form (from Dan North's work on Behavior Driven Development) is the textual form "Given, When, Then", but there are a wide variety of expressions that I have seen used.  It really depends on what it clearest to those in the organization and the various stakeholders they serve.

I did a webinar on this, and if you didn't have a chance to attend, I strongly recommend you take a few minutes to review the recording.  Not only will you see practical examples of how this can be accomplished, but also how defining a "Domain-Specific Language" in this way can bolster the quality of every product you touch.  It is an extremely low-cost way to accomplish what turns out to be quite important.

Here is a link to that recording:

https://www.projectmanagement.com/webinars/877055/Domain-Specific-Languages-and-Acceptance-Testing