Effective communication: The importance of a common vocabulary

A key aspect of a delivering high quality software is effective communication between team members. In order for communication to be effective the sender and receiver have to be speaking in common, well understood terms. Creating a defined common vocabulary fills the role of definining domain and project specific terms unambiguously.

As software developers, we know the importance of accurately naming things. We give names to source files, libraries, namespaces, classes, variables, etc. Names have intrinsic value to us, they are one of the core elements of how we work our craft. Names to programmers are exact and precise, misspelling a name even by a single character (or case, depending on your language of choice) will generally cause an error. The contract between a programmer and his compiler demands clear, unambiguous communication. Humans, on the other hand, frequently attempt (with varying degrees of success) to communicate using less than exact terms.

In software projects we usually come up with informal names for the distinct pieces of the project. This allows developers to effectively communicate with each other quickly and unambiguously. This system generally works great when the need to communicate about aspects of the software stays within the development group; however, where it breaks down is when the stakeholders outside of the development group need to communicate about the project or the data it produces. Without a well defined, documented project vocabulary they are left to come up with their own terms which may not accurately reflect the actual implementation, or worse yet a term may be used by outside stakeholders that means something different than the meaning to the internal development team. As one can imagine, this causes confusion and needlessly wastes time.

Without well defined meanings for your software components and the data it produces, it becomes extremely difficult for those without specific domain knowledge to communicate about the system. Producing accurate reports from the data becomes nearly impossible when the meaning of a data point is not specifically known. Well documented names and definitions also have a big impact on the maintainability of an application.

Taking the time to come up and document meaningful names for the components, functional areas, and data of a project will help facilitate accurate communication about a project, both inside and outside of the team. It will make your meetings shorter and more productive, will increase the maintainability of your application and data, and will reduce bugs.

Project definitions don't have to be anything fancy, they should just clearly and unambiguously define specific key terms relevant to the project. When someone reports that the "MonthlyWidgetCount" doesn't appear to be correct, there should be no question as to what they are talking about or what the definition of that data point should be. The project dictionary should clearly state that the "MonthlyWidgetCount" is the total number of widgets there were produced between the first date of the month and the last date of the month, inclusive, including all defective widgets that were discarded.