RSS
13 Mar 2021

Agreeing on a Common Language

One of the first things that should happen when undertaking any new software project is defining and agreeing on a common language to be used when speaking and writing about that project. Even if the people involved in the project all speak the same language you should assume there will be differences in interpretation.

For example, if the project is to build an integration between two systems the word 'integration' is too vague and will mean different things to different people. Adding words informally when talking about it may feel like it is making the meaning more clear but those extra words will not be consistently repeated and their intent will be lost. Your team might propose building a 'one-way integration' between the new system of record and the legacy system to alleviate the user's work of duplicate manual entry because the legacy system will continue to serve some role until another system is implemented to take over that work. If that sounds very specific it is because that is exactly the project that led to this post.

The phrase 'one-way integration' will only be repeated ad nausem for a short period and possibly only by some members of the project. Soon the word 'integration' will be used by everyone but with a different meaning in different individual's minds. The development team who proposed the 'one-way integration' due to the time and resource constraints available will continue to think of the project as one-way communication between two systems. Other people involved in the project may quickly forget the one-way aspect. It may be that they were never sold on the idea in the first place or that integration to them means bi-directional communication so when they hear 'integration' over and over as a description of the project they just assume it means bi-directional.

I take full responsibility for the naming and the lack of an established language for this project and in hindsight it is easy for me to identify many other issues related to the communication of the project both before it began and along the way. I do think there is a lesson or two that can be learned at least for myself and hopefully for other people as well.

  1. Everyone needs to agree on the goals of the project and anyone who is not immediately involved but who may eventually be effected by the project needs to have a voice in the discussions leading to the creation of the project.
  2. We should be extremely explicit, not only about the goals of a project, but about the language of the project. This should include establishing a repository of terminology that is accessible to anyone involved in or interested in the project.
  3. We should regularly review the language of the project to verify the interpretation has not changed across members of the project.
  4. The acceptance criteria of the project should be established and agreed upon before the project implementation begins. Indeed if agreement about this cannot be reached it probably indicated that the project idea needs to be re-worked.

Of course this requires many different people to agree not only about the project but about how projects should be created and implemented. It would also seem to imply that a meeting moderator would be beneficial and I have definitely felt this to be true during the project. I'm not confident that the company I currently work at would be amenable to this approach, especially coming from a lowly developer (which is an unfortunate and pervasive view of the role of a software engineer at this non-software company.) But, I will certainly think about these things when I am next involved in the creation of a new project.

Tags: software
Other posts
Published with ~org-static-blog~
Font Fantasque Sans Mono
Creative Commons License
stephancleaves.com by Stephan Cleaves is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.