Establish a common set of terms understood by the core team
Phases
Suggested Time
1 hour
Participants
Core team, subject matter experts
Why do it?
- Helps establish clear names and definitions for domain concepts
- Helps eliminate duplication and inconsistency in the codebase and in team conversations
- Helps Give new team members an easy way to onboard into the domain
When to do it?
We try to do this during Discovery or Framing in order to establish a baseline vocabulary. It’s advisable to do this prior to delivery so the code that’s written reflects the business domain language from day one. It’s also worth revisiting this throughout the project as new domain terms are uncovered.
What supplies are needed?
- Whiteboard, large wall, or digital version like Miro
- Sticky notes
- Sharpies / markers
How to Use this Method
Sample Agenda & Prompts
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
Success/Expected Outcomes
Success happens when you’ve identified a starting list of common terms and given a definition to each. Congratulations—you’ve created a Ubiquitous Language glossary!
Facilitator Notes & Tips
If you find yourself running low on time during share out, consider prioritizing the terms most closely related to upcoming work. This way you’ll be able to work those terms in the most imminent stories so they get built into the codebase.
Try as hard as you can to have one or more domain experts in the room with you. Without people present who can represent the subject matter, it will be tougher to converge on a shared language that represents the business reality.
Real World Examples
