What Is Example Mapping
Example Mapping is a backlog refinement technique that helps you structure your team’s conversation around a backlog item. The conversation focuses on drawing out all of the relevant acceptance criteria (or rules), related scenarios and pertinent questions associated with the backlog item you are discussing.
An example mapping session identifies:
- Examples that can lead to acceptance tests.
- Acceptance criteria that indicate agreed upon constraints about the scope of the story
- Questions about scenarios where your team isn’t clear on expected behavior.
- Assumptions you’re making in order to move forward
- New backlog items that you discover as a result of the discussion or sliced off and deferred from delivery.
An Example
Here is the result of an example mapping session for a backlog item from the Agile Alliance Conference Submission System. This particular backlog item is providing the capability to review sessions that people submit via the submission system.
When to Use Example Mapping
It’s best to have an example mapping conversation on a backlog item shortly before the team plans to start development work on it. That allows you to gather other information about the backlog item but also gives you a chance to resolve the questions you identify so that the team is not delayed in their development work.
There is no right answer when it comes to how frequently you run an example mapping session. You could have the discussions on an ad hoc basis meaning that you have a discussion whenever you’re getting close to needing a new backlog item to work on. You could also have a regularly scheduled session where your team discusses two or three backlog items. Matt Wynne recommends running example mapping sessions every other day and limiting the discussion to a single backlog item and time boxing the discussion to 25 minutes.
Ultimately, your best bet is to try out a couple different variations on timing and see what works best for your team.
Why Use Example Mapping
There are several benefits to using example mapping.
Example mapping helps your team build a shared understanding of the backlog item that your team is working on. The discussion of different scenarios helps your team establish an agreement to what the backlog item will or will not do in various scenarios and also understand the expected behavior of the system after you’ve delivered the backlog item.
Example mapping helps your team identify questions pertinent to the backlog item so that you can resolve them before the team starts development work. Answering those questions helps you minimize interruptions during the actual development effort.
Example mapping gives your team a jump start on test planning and testing. The examples you discuss become your test cases. Plus, having an agreement about what you’re going to test helps avoid bugs that pop up as a result of not handling specific scenarios.
Example mapping helps your team to identify and discuss the assumptions everyone is making about the backlog item so that members of your team aren’t operating under different and potentially even conflicting, assumptions.
Example mapping helps your team avoid overly large stories. When you discuss a backlog item and identify all the pertinent scenarios you may find that you don’t need to account for certain scenarios or you identify a way to split the backlog item into multiple backlog items that can be implemented independently.
How to Use Example Mapping
Get together people from your team with different perspectives. At a minimum, you should include:
- Product person who’s discussing the backlog item from the perspective of “Have I described the problem I want solved?”
- A developer who’s looking at the backlog item from the perspective of “ Do I have enough info to solve this problem?
- A tester who’s looking at the backlog item from the perspective of “What happens when?”
You can certainly include others – such as someone looking at the backlog item from a user experience perspective. You may also choose to include the entire team if everyone finds value in being involved in the conversation, but don’t feel as though it is an absolute necessity to include everyone.
Grab a pack of multi-colored index cards and sharpies to capture the key pieces of information as the discussion unfolds.
Write the backlog item you want to discuss on a yellow index card and place it at the top of the table.
Write each acceptance criteria that you’re already aware of on a separate blue index card. Put those on the table underneath the yellow backlog item card.
For each acceptance criteria, decide if you need examples to further explain it. If an acceptance criteria does need examples, write each example on a green index card. Use the Friends episode naming scheme by starting each example with “The one where…”
As you discuss the rules and examples, you may uncover questions that no one in the discussion can answer. Write the question on a red card and continue with the conversation. Having the ability to write your questions down prevents your team from spiraling down a rabbit hole during the discussion.
Continue the discussion until the scope of the backlog item is clear or you run out of time.
Caveats and Considerations
Example mapping is a simple technique, but there are several important nuances.
Examples further explain acceptance criteria
It’s not unusual to hear teams set a standard that all acceptance criteria has to be written in the form of examples. This indicates that the team views acceptance criteria and examples as the same thing.
They aren’t.
Examples provide further description to acceptance criteria, but should only be used when the acceptance criteria needs further clarification.
There are some acceptance criteria that are very clear cut and do not need further explanation.
There are other acceptance criteria that benefit from further clarification from examples.
Examples help you identify opportunities to split a backlog item
As you identify examples for the backlog item, it may become apparent that the backlog item is bigger than what your team typically tries to tackle at once. The acceptance criteria you identify, and sometimes even examples, provide good pointers for splitting your backlog item.
When you decide to split your backlog item look for ways to defer as much as possible. Solve the core problem and save the complexity for later. You may find out you don’t need it.
Don’t Bother with Gherkin Yet.
Avoid the temptation to write out your examples in full blown Gherkin syntax (Given, When, Then) as you’re discussing the example. The focus of the discussion is to identify examples, not to fully flesh them out. That’s one reason Matt Wynne suggested the Friends naming convention where you preface each example with “The one where…”
If you find you have some uncertainty around what should happen with a given scenario, you may need to provide some more information, but you can do that without going down the Gherkin rabbit hole.
For example: Scenario: The one where session is on Reed’s TracK
- Reed is a reviewer for Coaching and Mentoring track
- Submission submitted on Coaching and Mentoring track
- Reed can review session.
If you don’t know the outcome (then) for a scenario, that’s a great use for a question card. A question card may also be a better choice when you’re not sure if a scenario is relevant or possible.
So should we bother writing Gherkin?
There’s certainly value in writing things in the strict Given, When, Then construct, especially if you’re automating your acceptance tests with a tool such as Cucumber or SpecFlow.
Writing things in Gherkin helps you to nail down the domain language for your product and helps to clear up cases where team members are calling the same concept different things.
Matt Wynne suggests that once your team is up and running, with a fairly mature domain language, the product person should spend their time and energy in the example mapping session, and leave the actual writing of Gherkin to developers and testers. The developer and tester can ask the product person for feedback in order to see how effective the example mapping exercise transferred the product person’s knowledge to the rest of the team.
Example Mapping in a Distributed situation
As teams go remote by choice or out of necessity, they are figuring out some ways to do example mapping in a remote setting. Some hacks that Matt Wynne suggests:
- Bullet lists in a shared Google Doc
- Google Sheet with colored cells to represent the different colored cards
- One of the many white board or mind mapping tools.
The secret is that the tools you use don’t get in the way of the conversation and learning.
Additional Resources
Introducing Example Mapping
Before you pull a user story into development, it’s crucial to have a conversation to clarify and confirm the acceptance criteria. Whatever you call this conversation, many teams find it hard; it’s unstructured, it takes too long and gets boring. The result is they don’t do it regularly or consistently, or maybe they just give up on it entirely. Matt Wynne discovered a simple, low-tech method for making this conversation short and powerfully productive. He calls it Example Mapping.
Stories, Rules and Examples
Matt shared these slides from a talk he gave at BDDX2014 where he described the relationship between stories, rules, and examples, and why it can be helpful to use concrete examples to help explain rules.
What do user story conversations look like?
User stories are placeholders for a conversation. Who should be included in those conversations? When do you have these conversations? What should you talk about? How do you remember what you said? I provided some answers to those questions in this Agile Alliance post.
How to build shared understanding with example mapping
This session introduces example mapping, a technique that helps you structure your conversations and build a shared understanding.
How to describe user stories to build shared understanding
Ultimately, example mapping is a technique you use to figure out how to gain a deeper, shared understanding about part of your solution, one story at a time. This post describes some techniques you can use to describe user stories help you build shared understanding of your product and the outcomes you seek.
Example Mapping – Draft.io
While it’s helpful to be in the same physical location to do example mapping with your team, you don’t have to be. The folks at Draft.io, a flexible workspace for collaboration, information mapping, and visual management, put together this overview of example mapping including a couple of images of what example mapping might look like using Draft.io.