In the late 1980s and early 1990s I used to help companies analyze large systems and generate project plans (Gantt charts). During those activities, I would often see two people having a conversation using the same word, but talking right past each other. Even though it was clear to the casual observer that they were both using the same word in two totally different ways, they both clearly thought they were in agreement. The end result was that a software system with that ambiguity built in!
One solution I sometimes use as an immediate fix in these situations is to choose a foreign word, like an obscure Russian word, and agree to use that term to define the concept under discussion. By using a word that nobody knows, we eliminate the problem of any historical baggage associated with the term. That simple technique often works in the moment and helps bring about agreement on how to refer to a concept.
Start with a Glossary
Situations like these are why one of the first documents that I write on any project that I work on is the glossary. I'm convinced that before writing user stories (or requirements in another format), we must agree on the basic vocabulary that we use to draft those requirements. If you don't have a glossary of your core terminology, it should be the first thing you start working on.
To help bring this point home, I will often play up my outsider role when teams are writing user stories. I explain that if I make an assumption about a team's vocabulary I will most certainly be wrong, so I will not presume to understand any of them. That gives me license to ask all of the obviously “dumb” questions about what a word means—exposing much of the ambiguity surrounding those terms along the way.
Glossaries Are Important, but Hard
Though I believe glossaries give teams by far the most bang for their buck, I have found that writing good glossary entries is very difficult for most people. Doing it well requires a clarity of thought and a selection of words that can be difficult to achieve. Often people have to force themselves to challenge the words they are using to make sure there really is a clearly defined term with each concept.
The following guidelines are a good place to start:
- In most cases, the rule is one concept, one term
- Two words are only synonymous if they can truly be used interchangably to refer to the same concept.
- Try to avoid homonyms (words that sound alike but are spelled differently)
- Offer an antonym when possible to provide greater clarity around the often subtle nuances of terms.
- If there are nuances distinguishing two people’s use of the same term, then consider qualifying one or more uses of those terms. For example, two people are using the term “client” in slightly different ways. If so, consider defining a “Type 1 Client” and “Type 2 Client” and perhaps defining “Client” to mean “either a Type 1 Client or Type 2 Client.”
- Entries should be in uncapitalized unless the entry is a proper name.
- Direct people to related glossary entries (see description below).
Consistency Is Key
The terminology in the Agile world can be at times confusing and contradictory, so in my book Essential Scrum, I made a conscious effort to be consistent. When I used a word that I considered to be important or critical to the definition of the topic, I would define it in a glossary. I spent a substantial amount of time writing glossary entries. I also reviewed all 500 pages of the book to make sure every time I used term I used it consistently with how I had defined it. My effort did not go unnoticed. Many people have told me that they appreciate the clarity of the words that I used when describing topics—not to mention the fact that they could look up any critical term in the glossary and understand my definition of the term.
If you look at the overview text in the glossary on the Innolution.com website you will see that I define a couple of meta terms.
- See refers to a preferred term or to a term whose definition serves to define the term in question.
- See also refers to a related term.
- Synonymous with refers to a synonym or term with a nearly identical meaning.
- Contrast with refers to a term with a substantially different meaning.
I borrowed this structure from the IEEE nearly two decades ago, and I've been using it ever since. I find it particularly helpful to use these meta-tags at the end of glossary entries to refer the reader to either preferred terms, related terms, synonymous terms, or antonyms.
I encourage you to have a look at the glossary on the innolution.com website as an example of how you might consider drafting your own product or project glossary. If you don’t have a glossary for the product or project that you are working on, start writing one NOW!