Creating a common lexicon for software development in your organization

In this article, we'll explore the need for a common lexicon for your software development team and look at what you need to do to create it.

While at lunch with a buddy of mine the other day he shared that he came to a startling revelation. He was listening to a presentation on Services Oriented Architecture (SOA) the day before and realized that much of his job was terms definition. Simple things like, what does the word "Enable" mean to you. What is an Enterprise Network Bus?

In software development we often use terms with one another which are poorly defined and have different meanings to different members of the team. We assume that when we say "factory pattern" the person on the other end understands us the same way they understand us when we say "cat."  This is, however, rarely the case.

In this article, we'll explore the need for a common lexicon (see the definition for details) for your software development team and look at what you need to do to create it.

The Tower of Babel

"The LORD said, 'If as one people speaking the same language they have begun to do this, then nothing they plan to do will be impossible for them. Come, let us go down and confuse their language so they will not understand each other.'" The Holy Bible, New International Version, Genesis Chapter 11, verses 5-7

When people speak with one language, one understanding of each other, they are able to accomplish almost anything. The more that we are able to speak, hear, and understand each other the less time is wasted on stupid mistakes and misunderstandings.

Most people have had situations where we've given direction to someone and come back only to find that the direction we gave wasn't clear to the recipient. Or at the very least we've taken some direction from someone and when we demonstrated what we had done they indicated they were expecting something different. (This still happens when my wife asks me to do something.)

It's annoying but in software development it's costly. Estimates vary but the general consensus is that over 40 percent of a project's budget may be consumed by rework. If you consider that most of this rework isn't because of poor understanding of how the technology works, but in because of poor communication, you can see a great potential for improvement in the performance of your team by communicating better and reducing rework.

The foundation for creating less rework is in developing a common language that you can use to communicate as clearly as possible. It will never be perfect, but having the same understanding of a word will radically improve your chances of fully understanding what someone else is communicating.

Relearning existing vocabulary

One of the challenges with meeting the call to develop your own lexicon, your own language, with your developers is building common experience and common understanding of the things that you already believe that you know. You may believe that you know what the other person means but in reality you probably believe something slightly different.

Take for instance, when I said "cat" above. You may have thought I was talking about "Fluffy" the white haired Persian cat that you had as a child. Or perhaps you were thinking of the Calico cat you have today. I was, however, actually, referring to one of the Bengal tigers that I recently saw. Should I have pointed out that I was speaking of a "big cat"? Probably, and if I was giving direction I would have. However, even big cat isn't specific. Would I be referring to a leopard, a lion, or a tiger?

The point of all of this is that we all share a vocabulary but we each define the words slightly differently. The trick is to pull the definitions of a group of people together as much as possible so that you can use words and know what they will mean to your team members.

One technique for doing this is finding examples of articles, white papers, etc. that defines the term and expands upon it's meaning. For instance, Services Oriented Architecture is a difficult thing for most people to define. However, you can bring folks to a common understanding by asking or encouraging them to read the same article on SOA as the rest of the team. While everyone may not agree on every specific point about SOA raised in the article it creates a reference point that can be used to anchor a definition that everyone on the team agrees upon.

That anchored definition allows you to define other terms in relationship to it, and to other terms, and helps to strengthen the continuity of understanding between team members. However, even well understood, anchored terms may not be enough.

Creating new vocabulary

Your existing vocabulary is a good start. With seasoned practitioners there's a wide variety of words and phrases that have – or can have – a specific meaning. However, there are times when the existing vocabulary just won't cut it. When you're trying to describe your own techniques, processes, or methodologies, you may find that the existing vocabulary just doesn't cover it.

A former coworker of mine, David Feinberg, has a dream. He wants to get a new word added to the dictionary. It's a great dream, and I wish him luck. Of course, whether he does or doesn't succeed in his goals, he's good at introducing new words into his organization. The beauty of these words is that they mean a specific thing to everyone in the organization – and there is little chance of anyone outside the organization having a different definition.

Although it may seem like having others not know the word would not be a good thing – it can be. It's good because there's a low chance that the word will be misinterpreted. Because there are no other context clues as to the meaning of the word, it's likely that the only definition that the team will develop is the one that is intended.

The most difficult problems to troubleshoot, diagnose, and fix are those which are not clear and repeatable. The same goes with communications. If you can't see that it's a problem, and if it's not a problem all the time, you will probably have a hard time getting people on the same page. A new vocabulary item has the benefit of being understood or not understood, but with a very low probability of being understood incorrectly.

Culture of precision

One of the great benefits that I get out of having different professional editors looking at more than 80 percent of everything that I write is that they have encouraged me to be more specific in my writing. I can't just say things happen – I have to be more specific about what, when, for how long, etc. We all speak in somewhat general terms when we are speaking. It's less formal and we're thinking on our feet, however, the general way that we approach speaking leads to a certain amount of ambiguity and imprecision. The most frequent situation that illuminates the lack of precision is when we ask someone a question via email. We indicate the question but rarely do we actually indicate a deadline for the response. We leave ambiguity in how long the person has to respond to our inquiry.

The impact of a culture of precision in speaking and writing is subtle. It is subtle because you can develop your own lexicon for developers without it; however, it's like a catalyst. It can accelerate the process. By making the team hunger for precision in their communications they will seek out the most precise words they can find to express their ideas. Instead of just being satisfied with the idea that a data entry screen is necessary, they'll begin to explore which of the standard operations they need. Instead of data entry screens you'll get something like. "We need an edit screen for the customer list capable of adding, reading, editing, and disabling a customer. We never delete customers so that isn't necessary."

Perhaps it takes a few more words to communicate like this, perhaps even a minute's worth of time is "wasted" by this precise way of communicating, but that certainly takes less time than coding a delete feature into a screen that will never be used because the business process doesn't allow customers to be deleted.

Culture of refinement

A culture of precision is not only about speaking and writing in precise terms but is also about learning how to hear with precision. In other words, communicating in precise terms also requires that the listener verify the meaning that they attribute to the words that the speaker used. A culture of refinement is one where listeners are encouraged to challenge their understanding of what the speaker said by echoing back the understanding – and not the words. This leads to an automatic refinement of the message which makes it even more precise.

The Humanist approach to psychology is based upon the idea that you tell the person what you just heard. The technique is both validating to the patient and illuminating to the counselor. The patient feels like they're being truly heard and has an opportunity to expand upon the details of the situation or how they feel. The counselor verifies their understanding of the patient and in return understands better.

The basic format is the speaker saying something like "I believe we need a SOA-based approach to this problem." The recipient (or one of the recipients in a group setting) says something like "I understand that you believe Web services are the right way to go with this project." The response doesn't use the same words that the speaker used. It uses a slightly different construction and in this case with a slightly different meaning. The result should be the speaker responding with "Yes, but I believe we need to address queuing and the transactional nature of what we're doing. I also believe that we have to focus on maintaining loose coupling." This interchange has illuminated that the speaker believes that queuing (asynchronous operation), transactional processing, and loose coupling are important components of the solution. Without this reflection of meaning back to the speaker this information would have never been shared.

This culture of refinement, where everyone is trying to refine their understanding of what is being said can be a bit overwhelming at first as it initially increases communications, however, it has the potential to substantially reduce rework.

The world at large

One of the challenges that occur when you create your own lexicon for communication is that the world creeps in around you. You're overwhelmed by messages from the rest of the world which may have a different definition of your terms than the group defines. That's one of the reasons why it's important to find your own vocabulary so that you don't have to battle a different meaning in the world at large. Prefixing terms with 'OurCo' such as in OurCo-SOA can help to keep the distinction even when the world has a slightly different or less refined meaning.

Ultimately there is one major caution with your lexicon. That is not to make it conflict with the meaning of the world at large. So you wouldn't, for instance, want to define a Web service as a Web site that users use on top of existing mainframe applications. The definition would be substantially inconsistent with the definition used by the rest of the world and would simply lead to problems of misunderstandings when you try to bring in new people, communicate with your peers, or even get consultants "up to speed" as they come in.

The best way to view your lexicon is a dialect. Something that resembles the way the outside world communicates, but has special and unique meaning to the team – a meaning that makes it easier and more productive to communicate.

The mind

You may not need to create a whole new language or learn some obscure language like Klingon but you should consider how you communicate with your team and how you can create your own lexicon for communicating back and forth with one another.

Learn to anchor your key terms and apply your own definitions to new words to form a stronger bond between the meaning behind the communication in the mind of the speaker and the meaning behind the communication in the mind of the listener.