Example Mapping HowTo

Where we look at the mechanics of Example Mapping.

Many teams struggle with ambiguous user stories or late discovery of edge cases. Example Mapping offers a lightweight way to turn unclear stories into concrete, testable specifications that bridges the gap between product and engineering.

It is a short structured conversation technique used to clarify, exemplify, and slice user stories. It takes up to 25 minutes and helps a team shape a story into exact acceptance criteria (in example mapping called rules) with examples that can be used to exercise the criteria.

It was first described by Matt Wynne on the Cucumber blog. After that it has been used by many teams to iron out ambiguities in user stories.

Preparation

Before starting, the team should have a well-defined story, ideally one that’s expected to be implemented soon (within a few days or a week). The shorter the time between mapping and implementation, the more value you get since the team will better remember the conversation. Many teams run example mapping sessions several times a week, just before implementation.

Make sure everyone with key knowledge is present. If the story touches on compliance, security, or privacy, include people with expertise in those areas. This is the perfect place to surface such requirements early. Their input can help refine slicing and improve design decisions. Naturally, include the usual “three amigos” (product, test, and engineering) as well as UX.

But also be mindful about how many participants you have. If you find that the group grows to more than six to eight people this may well be an early indication that you should slice the story further before you example map it.

The workshop

The workshop is short, it only lasts until one of the below has happened, whichever comes first:

The story is done, there are no more rules or examples left to discover.
25 minutes has passed.

In other words, this workshop will never take more than 25 minutes, but usually less.

Start with presenting the user story to the group. This is usually done by the product owner to product manager. As you do, write the story title on a yellow sticky.

Next, list all already discovered rules (acceptance criteria) on blue stickies.

Now the group starts to challenge the story narrative to discover more rules and to find examples that illustrate how the rule is exercised. Examples are placed under each rule on green stickies. If questions arises that the group cannot answer they are noted down on pink stickies. You may also discover new stories. Write them on yellow stickies and park for a future session. You will find a couple of slicing heuristics you can use below.

Images illustrating board layout

So, the colour coding used is:

User Story -> Yellow
Questions -> Pink
Rules -> Blue
Examples -> Green

Keep going until one of the two exit criteria are met, I.E. you are either done or 25 minutes has passed. The reason why you should not go longer than 25 minutes is twofold. First, this is a pretty intense and highly focused workshop. It’s taxing to do. So to ensure you stay focused for the duration you can only do this a short time. Secondly, since it’s so short it’s easy to fit into the team’s calendar. Meaning it’s practical to do just before you start implementation of the story.

Also, it is really important to stop at one single story. Never start a new one if you’re done in less than 25 minutes. The reasons are the same as the upper time limit. Short, focused, easy to plan and have as part of your daily work.

Heuristics to decide if the story is ready

The outcome of the session will help you determine if the story is ready to be implemented, if there are outstanding questions you need answered before starting work, or if you should slice the story into smaller parts.

When the board is balanced

If, when you are done, you have no more outstanding questions, there are a maximum of 3-4 rules and no rules have more than 3-4 examples the story is ready. The examples need to be good enough that when the automated tests written from them passes, the story is ready to be deployed. Use thumb voting to gauge the team’s confidence.

When there are outstanding questions

If you have any pink stickies left, I.E. questions the room cannot answer, it may be that the story is not ready to be implemented yet. If the questions are minor and you’re sure they will be resolved in a day or two, you’re probably good to go. If not, resolve the questions and then schedule a new workshop. Again, use thumb voting to gauge the team’s confidence.

When there are more than 3-4 rules

Any story with more than 3-4 four rules is too complex to start work on. However, the rules you have defined can now be used to find places where you can slice your story. Find cohesive groupings of rules and slice the story along these lines.

When a rule has more than 4 examples

Just as with rules to a story there is a maximum of examples to a rule. We do not want rules to be to complex. This makes it hard to fit in your head, let alone implement and test. But, just as with rules to a stories, you can use the examples to identify cohesive groupings of examples. Use them to slice rules.

Naturally, if slicing rules pushes your rules over the threshold for what’s acceptable for a story, you also need to slice the story.

When you run out of time

If 25 minutes is not enough to complete a story the story is too big. This often comes down to a combination of the above three. Again, look for cohesive patterns within questions, rules and examples to find seams that you can slice along. Then, when slicing has been done, re-convene and take the most important story first.