Skip to main content

Establish a Common Vocabulary

Context​

Microservices are being adopted. There are multiple teams, each responsible for their certain microservice(s). Teams communicate and collaborate with each other and among their members as well as with other stakeholders about the project.

Problem​

  • Everyone has a slightly different understanding of the domain
    • Communication between teams (or even within teams) regarding the bigger picture and APIs often leads to slight misunderstandings

Solution​

Introduce a common vocabulary about the domain (model) that everyone agrees on. The language should emerge from a preceding domain analysis. Involving domain experts in the process will ensure that the common vocabulary will inherently increase the communication effectiveness with other stakeholders as well.

This "ubiquitous" language - that's what it is called in Domain-Driven Design (DDD) - evolves with the progress on understanding the underlying domain. The goal is to resolve ambiguities over time.

We suggest to introduce a process that revisits the common vocabulary regularly to revise and refine it. The result should be compiled into a dictionary as a single source of truth accessible for everyone. The new insights should be spread among the teams, so there should be communication between teams to propagate them. E.g., regular cross-team discussions or use a thematic board to manage the dictionary in the first place.

Maturity​

Proposed, to be evaluated.

Sources of Evidence​

L7:

  • "ubiquitous" language and domain model make code better understandable and easier to maintain

L22:

  • use "ubiquitous language" promoted by DDD
  • all developers have to use this "dictionary" => makes sure to operate within the same domain

L52:

  • Use ontologies to define common vocabulary for enterprise architects
  • => helps to share information based on explicitly defined concepts

L61:

  • Context: architectural language for microservices
  • can help to reason about system as a whole, performance analyses on system qualities, coping with dynamic and changing aspects of app at runtime
  • powerful communication instrument to enable better communication with both technical (devs, architects) and non-technical stakeholders (customers, users)
    • get the level of abstraction in communication right
    • with a shared technical vocabulary

Interview A:

  • What is the product? is a very important question that needs to be answered and they speak about often
  • "Lets speak about the same thing"

Interview C:

  • Common vocabulary improves communication between teams
  • Defined domain concepts help to communicate better in interface discussions