Effective Domain Modeling, a step-by-step guide

Cover image
12 min read
Software Engineering, Modeling, Mindmap
All the things I wish I knew before I started doing a Domain Model.

Introduction

I started my Software Engineering career in a start-up, and I did not bother with Domain Modeling — have I known what it was. Instead, I’d take every shiny feature the Product Manager talked to me about and rush into the code. This feature-first mindset made it painful to build durable software. At each iteration, I refactored a lot due to shortcuts taken the sprint before. The technical debt kept growing.

Today, I’m a Machine Learning Engineer working for the leader in Energy Management and Automation, Schneider Electric. I’m in charge of a project of a dimension I had never seen before. To design a Machine Learning Framework to scale the feature engineering and machine learning model life-cycle management at the Enterprise Scale.

Having no idea where to start, I adopted the following modus operandi to learn about the Domain. Indeed, if I was well aware of the Data Science part of the process, the maintainability, auditability, and scaling requirements of the framework were a whole new ballgame compared to my previous projects.

The Domain Model Interview process I detail below turned out to be extremely useful to generate a complete Domain Model that helped me to design this Machine Learning Framework. Thinking through the Domain Model made it easier to identify the critical path for the framework’s development. Also, it helped ensure the hard requirements for maintainability and auditability were built in and not bolted on.

Domain model
Figure 1: Having a correct Domain Model enforces correctness in software.

But what do I mean by Domain Model anyway?

Building a basic model starts with extracting the noun and verbs from the user story to identify the key objects, attributes, patterns, and relationships.
— Alibaba Tech’s Team, in Making a Case for Domain Modeling

Getting a Domain Model requires connecting with Domain Experts. Also known as Subject-Matter Experts, Domain Experts are individuals with substantial experience in the field. Subject-Matter Experts help identify critical entities of the Domain as well as how they relate to each other.

I learned that acquiring Domain Expertise from Subject-Matter Experts to build the Domain Model is a journey on its own. In this journey, you develop interpersonal skills that expand and complete your engineering expertise.

In this article, I provide you with a step-by-step guide on how to run a Domain Modeling Interview. It involves those four steps;

  1. Before the interview — Define the goals, contact the experts, and invite them to read this article.
  2. Running the interview — Acquire Domain Expertise and become a junior Subject-Matter Expert.
  3. After the interview — Do your homework and connect the dots.
  4. Deliver the Domain Model — Make the Domain Model knowledge durable and available.

Domain Modeling is an iterative process, and you’ll never get it 100% done. Depending on the complexity of your Domain, you’ll need to reiterate the sequence:

1. → 2. → 3.

two to three times to get the 80~90% understanding that can get you going.

Let’s dive in!

1. Before the interview

Define the goal and connect with the appropriate Domain Experts.

Leading a successful Domain Modeling Interview has some prerequisites. Here are the steps I followed to prepare such interviews in a time-efficient fashion. Let’s review what you need to think about before meeting the Domain Experts.

1- Refine the scope of your Domain Model Interview

First, examine your level of knowledge about the Domain and review the resources available. Then, refine the scope;

Do you want to model the Domain at a macro level, or do you want to zoom in on a particular sub-component of the Domain? Now that you have refined your area of focus, you can identify the relevant Subject Matter Experts to contact. Look for the Domain Experts driving the product discussion and signing-off the marketing requirements about this part of the Domain.

2- Contact the relevant Domain Experts

Now that you know who can fill your knowledge gap, reach out to those identified experts. Send them an invitation for a 2 hours long meeting and explain to them the goal of your encounter. You want them to read this article beforehand, so they understand what you mean by “Domain Modeling.” Ideally, target two domain experts, so that you can get a consolidated story about the Domain.

What if various Domain Experts have different opinions about the Domain? In this case, it is better to have separate meetings at different times with each group. You better go one session at a time rather than referee a single meeting with all groups.

Having too many Subject-Matter Experts in the room can spoil the broth. Especially if the groups have competing agendas.
— Tom Whitehill, Senior Cloud Solutions Architect at Schneider Electric.

3- Prepare the ideal environment for the interview

The place where you meet for the Domain Modeling Interview must have the following features:

  • Have whiteboards and plenty of markers. — A Domain Model Interview is a collaborative meeting. Having two whiteboards is ideal, for example, to re-write the Domain when things get messy on the first whiteboard (no worries, that’s part of the process). It also makes it easier to involve everyone in the conversation.
  • Find a quiet space. — Record the meeting if everyone is OK with it.
  • Have low potential for distraction. — Fleshing out the Domain Model requires the undivided attention of all the attendees. Gently ask the attendees to put their phones away and reduce the potential for disruption.
  • Find a spacious place. — You might host three to four persons. Make sure the area won’t feel crowded so people can stand up and walk around the whiteboard(s).

Some additional protips

  • ✅ Having a real-life domain modeling interview is more effective than a web conference to get people involved in the discussion. A real-life encounter also helps in building trust and deciphering cues of disagreement or misunderstanding.
  • ❌ Avoid post-lunch and late day schedule. Going through a Domain Model Interview requires a significant cognitive load from the attendees. Make sure they are in the best condition to focus.

Before the interview — Summary

Adopt a divide-and-conquer strategy to dissect the Domain. Start with the overall model and then iterate on each subdomains, one session at a time.

Then, identify the right pool of Domain Experts to contact for each subdomain and set up the Domain Model Interview. Last but not least, make sure to explain your approach to the attendees, so they know what to expect from the interview. Ask them to read this article to get them acquainted with the process.

2. Running the interview

Become a junior Subject Matter Expert.

The objective of the interview is to get the pieces of the Domain Model puzzle that you miss. It requires curiosity for the interviewer to ask questions, even the simplest ones. At this stage, you want to get the Domain Experts to tell you a story. Make sure you collect every entity of the Domain on the whiteboard and re-arrange them as they relate to each other in the Expert’s mind.

1- Recording

Before getting started, ask everyone in the room if they are OK with you recording the session and do so. Announce the day, the topic, and briefly introduce the attendees to make your audio recordings easier to navigate. During the interview, take note of the timestamps related to the topics discussed.

For example, “1hour 30mins → Talking about the model training process”. Having audio records will help you in the next stage After The Interview. You can also start a new recording when you are moving to a different point in the discussion.

Voice memos are incredible to rework the Domain Model, for instance, to catch concepts discussed but not written down.

2- Get the interview started

Some people may be uncomfortable with the interviewing process, and it can be hard to get the discussion started. Here is my cherry-picked advice to get you started:

  • Stand up and show how easy it is to erase and redraw on the whiteboard; mistakes are cheap and easily corrected on a whiteboard!
  • Take the lead and show the example. Start to talk about your limited knowledge of the Domain, write a critical entity, and circle it. Ask questions to the domain experts without having an overly inquisitive tone. Your goal is to build a relationship of confidence and trust. You’re not challenging them; you’re here to learn from their Domain expertise. You’ll get better at this by practicing.
  • Sometimes domain experts may experience analysis paralysis at the beginning of an interview, not knowing where to start. Reassure them and invite them to begin by simply writing the first word that comes to their mind. You will start from there. You won’t get the perfect domain model fleshed out from the first shot anyway. It’s a journey. You’ll come back at it, change a few words, erase and re-write.

3- Write down every new word

The domain expert just mentioned a new entity you didn’t know? Grab a marker and write it down on the whiteboard.

That’s why it’s important everyone has a marker. Aim to minimize the friction of writing something down on the whiteboard. We talk faster than we write. Thus, having multiple pair of hands equipped with markers ensure we catch as many entities and relationships as possible.

4- Take pictures

Keep track of the process by taking photos of the whiteboard at different stages of the meeting. Those snapshots would help you if you erased things you shouldn’t have and want to rollback to a previous version of the domain model.

5- When things are slowing down

The software engineer or architect leading the discussion will ask questions when the interview is slowing down. Any concept that is not clear to you right now will undoubtedly be confusing to a colleague or a new-hire joining your team. There is no dumb question there, be curious.

6- Know when to call it a day

After some time, maybe one hour and a half, two hours, you won’t be making much progress.

Wrap it up by summarizing the modeling work done during the session and making sure everyone agrees on the Domain proposed: entities introduced and their relationships.

Pro tips

  • ✅ Focus on the vocabulary used. Make sure everyone agrees on the ubiquitous vocabulary of the model and stick to that ubiquitous vocabulary. If you think two terms are similar, ask the domain experts if they mean exactly the same thing. Having a consistent, ubiquitous vocabulary is paramount in domain modeling.
  • ✅ Be curious and humble. Ask the obvious questions. Especially about the vocabulary, ensure the domain experts have a shared understanding of the terms they employ. Especially, ask about concepts seemingly evident to the experts that you don’t understand. There may be a hidden misunderstanding here.
  • ❌ If the discussion gets to an inappropriate level of detail, refocus the discussion on the agenda you committed.

Running the interview — Summary

During the meeting, adopt the position that you know nothing about the Domain Model. Give full responsibility for explaining the Domain to the Subject Matter Experts. Start by asking the apparently obvious question, like: “What is a model in machine learning?”. You will be surprised by the dimensions of the answer.

3. After the interview

Do your homework and connect the dots.

Now that the interview is over your job starts. Go through the notes, pictures, and audio log of the meeting to consolidate your understanding of the Domain Model.

1- Play the audio recording of the interview

Go through the voice memo of the Domain model Interview. Whenever you hear an entity or a relationship not on the whiteboard, take note of it. You will ask the experts about it in the next interview or a follow-up email.

2- Consolidate the domain model

Based on what you heard, the pictures, and your notes, you now have a clearer vision of the domain model. Redraw it cleanly on a whiteboard and take a picture of it. It will be the starting point for the next meeting with the domain experts to ensure you are all on the same page.

3- Write a short note for each entity

Based on your understanding of the Domain, write a quick note for each entity to define it and its relationships to other entities. It will also serve as a basis for the next discussion with domain experts.

4- Identify the next step

Now, ask yourself if you have a complete understanding of the domain model or if you need further interviews.

Based on your answer, schedule an interview with the relevant Domain Experts (step 1.) or deliver the Domain Model (step 4.).

Pro tips

  • ✅ When redrawing the domain model, don’t waste your time on fancy tools when you are iterating. Nothing beats the flexibility of a whiteboard, markers, and taking a photo.

After the interview — Summary

Don’t overlook this post-interview work. It is tempting to schedule a new meeting with Domain Experts. Instead, take the time to go through your documents to refine your understanding and challenge potential inconsistencies. Doing this homework will boost your credibility by ensuring the Domain Model proposed is, and will be, a valid reference within your organization.

4. Deliver the Domain Model

Make the Domain Model knowledge durable and available.

Now that you have a consolidated understanding of the Domain Model, it is time to make it widely available within your organization. The Domain Model will be a reference for helping new hires getting on-board faster. It is also the basis for further class modeling, data modeling, and it will guide features implementation.

All of this depends on how easy it is to access the Domain Model within your organization.

1- Polish the Domain Model

Whiteboards’ pictures are OK while iterating on your Domain Modeling work. However, now that you’re about to deliver, you need a more appealing document.

The final Domain Model document should summarize the Domain Model at different levels of complexity. Each level is going into more details of the internals of your Domain. By packaging your Domain Model by layers of complexity, anyone in your organization can clearly understand the part of the Domain they care about.

2- Make it available

Obviously, right? The Domain Model should not be staying on your disk or simply laying in a chat discussion. You need to broadcast it. Add it to your project documentation.

3- Record a video walkthrough of the Domain

It may seem like a daunting task to your colleagues to go through the domain model. Make it easy for them. Record yourself doing a presentation of the domain model. It can be a video or a series of short videos requiring a low cognitive load (less than 5 minutes per video is ideal). Share those videos, pin them in the appropriate discussion channels, and refer to them in your project documentation.

4- Make a domain walkthrough part of the on-boarding

Add the domain model explanation to the on-boarding process of new team members. Choose the appropriate level of detail and walk your colleagues through the model.

Add the domain model explanation to the on-boarding process of new team members. Choose the appropriate level of detail and walk your colleagues through the model.

Having a Domain Model walkthrough will help new hires, especially with the vocabulary to use and the exact meaning of each entity they will see in the code afterward.

Protips

  • ✅ You worked hard on that Domain Model; it’s only useful if it is shared and referred to within your org.
  • ✅ Ask for feedback to colleagues familiar with the Domain Model when polishing it. You want to make it as digest as possible without losing any information.

Deliver the Domain Model — Summary

The delivery of the Domain Model is the critical step. Take time to polish and package it in an appealing format. Go through several drafts and ask your colleagues for feedback.

Domain Model Interview — Summarizing Diagram

Domain model process summary
Figure 2: You will go through several interview rounds before delivering the consolidated Domain Model.

Conclusion

The process I just described was incredibly helpful for building a scalable Machine Learning Framework with stringent requirements on maintainability. Following those guidelines, I grew a lot as a Machine Learning Architect. Running efficient Domain Model Interview is something I wish I knew how to do when I started my career, and I hope it will bring you as much value as it did to me.

Domain Modeling is an iterative process, and you’ll get better with practice. The guidelines provided are here to help you get started, adapt it to the customs of your organization. Conducting interviews with domain experts is the most exciting part of the process. It is a unique opportunity to ask all the questions you have about the Domain.

Special thanks

Thank you My sincere thanks to Tom Whitehill for his thoughtful feedback on my article and his repeated advice on Domain Modeling. Tom has more than 25 years of Software Engineering experience and made Domain Modeling his key to success in Enterprise-Scale software projects.

References