back to Practices
Tools

Ubiquitous Language

Establish a common set of terms understood by the core team.

Length

1 hour

Participants

Core Team, SMEs

Why Do It
  • Establish clear names and definitions for domain concepts
  • Eliminate duplication and inconsistency in conversations
  • Create an easy way to onboard new team members
When To Do It
  • At the beginning of the project
  • In the middl of the project when more information is available
How To Do It
  • Bring the SMEs and core team together
  • List common technical and business terms
  • Provide descriptions and explanations for each term

Step By Step

  1. Clearly outline the goal of the meeting:

    Example: “A form of technical debt we don’t often think of is the distance between the language used by domain experts and the one used in the codebase.”

    Example: “Our goal today is to get ahead of this debt by creating a shared understanding of terminology for our team that focuses on understanding, not semantics.”

    Tip: You can also present any anti-goals that may help steer the team away from rabbit holes. This is optional.

  2. Give everyone 10 minutes (or less) to individually write down as many terms as they can, 1 term per sticky note

    Tip: If you have many people participating in this activity, break into small groups. This will make the output more manageable.

  3. Next, set a timer for 30 minutes and have everyone write a brief definition for each of the sticky notes they’ve generated

    Tip: If you’re concerned about the volume of terms you may end up with, consider having participants only write definitions for the terms they think are least understood by the team.

  4. Have each person share out the terms and definitions they’ve identified. Cluster similar terms on the whiteboard or wall as they’re read aloud.

  5. Discuss any variances in the definitions, focusing on shared understanding over semantics. Avoid going into concrete definition mode.

    Tip: You will find that there might be multiple names being used for the same definition. Converge on one name and definition. If one does not exist, create one together.

  6. Take a picture of the wall to memorialize.

    Tip: If your team is fully co-located, consider keeping the sticky notes. Set notice space on a wall in your team area and reconstruct the term list there. This will provide the team with an always-accessible vocab reference wall.

Result
You’ve identified a starting list of common terms and given a definition to each. Congratulations—you’ve created a Ubiquitous Language glossary!