3.5 Modeling

Before we model, check the definition of ready:

Before starting

This activity adds fidelity to your engineering models — the diagrams and specifications that give enough technical depth to proceed to coding. Two drawing styles carry the weight: marble diagrams and sequence diagrams. Both are event-oriented, both model inputs/processes/outputs, and together they extend strategic and tactical event maps seamlessly into the engineering domain. Marble diagrams give you clear integration points for acceptance criteria (the specific tests that verify your work), and sequence diagrams give you an easy-to-read tool for modeling component interactions.

Why marble and sequence diagrams

Tactical event storming identified complex processes, but each is still represented by a single card on the map. That’s not enough to code from. A card like “payment terms calculated” actually represents about seven distinct business processes (base rate determination, risk-based pricing, payment calculation…), each with their own inputs and outputs. Risk-based pricing alone involves multifactor considerations:

Marble and sequence diagrams bridge this gap. Marble diagrams are event-oriented (they extend our event maps seamlessly) and operate on inputs and outputs (clear integration points for acceptance criteria). Sequence diagrams model component interactions, which is immensely helpful in a context-oriented architecture. Both are functional — inputs, processes, outputs — aligning with the design thinking used throughout the playbook.

Guide to modeling

This activity builds your technical design, naturally extending existing artifacts focused on business capabilities and architectural framework. Your team will need to be familiar with marble and sequence diagrams.

Inputs

• Your tactical event maps (for the current product increment).
• Supporting design artifacts, including capabilities and functions, strategic event maps, context map and service catalog.
• A current sprint backlog, populated with your highest value feature and aligned with the product increment.

Process

Take time to ensure everyone is well prepared and has a clear understanding of the workshop. (For more on workshop setup, see my formula for running a successful workshop.)

Prepare

With plenty of advance notice, send out links to team resources:

1. Refreshers on event mapping (especially important for participants who don’t use them often).
2. Links to important design artifacts.
3. Links to your current sprint backlog, along with a reminder that the exercise is very focused in scope (specifically, on designs for the current product increment).

Make sure your team understands marble and sequence diagrams. If they haven’t worked with them before, schedule a workshop ahead of time to explain and conduct some exercises.

During the exercise, stay on task. There will likely be opportunities to jump into other features not part of the current product increment. Keep the goal in sight — this design session is laser-focused on the current product increment. Anything outside that scope belongs to the future.

What not to do

Be careful the team doesn’t spiral and go too deep on specification — and conversely, that specifications aren’t “shallow” and lacking detail. How to decide when you have “just enough”:

1. No one has questions. Each team member should feel that the features, events and data they care about have been adequately handled.
2. Every data element is accounted for. No data elements “hitching a ride” for no apparent reason. Everything serves a purpose (or at least has a known purpose in a future sprint).
3. Strong “connective tissue.” Events and interprocess messaging are clear, including what happens if something goes wrong.

You’re done when it “feels right.” This isn’t just hand-waving. If everyone on the team agrees the design feels complete enough to move forward, you’re probably in a good place. Make sure there are no outstanding questions that must be answered this sprint — then move on.

Watch your scope. The current design activity is focused on your current sprint. You do not need to design beyond the current sprint. If it seems like you can’t continue without diving into future sprints and exploring “out of scope” design work, check your priorities and sequencing. Your implementation needs to be incremental, building on prior work. If you can’t move forward without jumping ahead, you may have to rethink your priorities and sprint sequencing — don’t just add more scope to your sprint. Recognize the mistake and go back to iteration planning to reset objectives.

What if you discover something out of scope that impacts the current sprint? Adjust course. Explore it — but recognize you need to replan the product increment and sprint before proceeding.

Execute

1. Develop models. Work collaboratively to develop your marble diagrams.
   1. For each card in your tactical event maps, start by modeling the card as a single, top-level granular feature in the marble diagram.
   2. Follow marble diagramming principles to “explode” it out, adding more depth and fidelity as necessary. Technical drawings that actually work offers detailed guidance and examples.
   3. Build your service descriptors — all of the information required to interact with the component; its inputs, processes and outputs.
   4. Outputs tend to align with verification steps. Your outputs should align with the acceptance criteria for every tactical step. Design those as business logic verifications that must happen.
2. Supplement drawings. When necessary, leverage sequence diagrams to augment your designs.
3. Specify all requirements. Include the technical implementation details at every level of breakouts: data inputs, outputs, parallel execution, retries, etc.

Your finished product should look something like this:

The finished product should provide a detailed, data-centric view of your application. You should be able to follow any data element through its entire journey. From that first “Prequalify borrower” card, you should have clarity on every piece of data: how it’s identified, the processes it runs through, the outputs, and the final verification steps.

Outputs

• Technical design artifacts. Marble diagrams and supplementary drawings that fully describe the technical implementation of your product increment at the data field level.
• Service descriptors. Metadata documentation that formally defines each service interface, capabilities, and contract with other systems (data inputs and outputs fully noted in your marble diagrams).
• Event data dictionary. A clear enumeration of all events your system will emit (noted on the marble diagrams).
• Verification steps. An inventory of verification steps (tests to perform, clearly called out on the marble diagrams).

Once you have completed the design artifacts for the current sprint, you’re ready to move on. In the next chapter we’ll write the technical specifications that go hand-in-hand with the design drawings. Technical specifications document more detailed behavior and specific use case scenarios — explicit rules and instructions for each process step. With the technical models, we’ve documented the “what.” With specifications, we’ll document the “how” — exactly what formula or decision leads to the expected result.

Next activity

• 3.6 Specification