Back to the news
Dev Gravity Gravity

Shaping user stories with “example mapping”

Example mapping blog post image


We introduced example mapping workshops as soon as we set up the development process at the beginning of the Gravity journey. Example mapping is a workshop for Agile teams to help structure conversation when working on a new user story. It has multiple benefits:

  • aligning the team on the definition of the user story
  • refining it
  • evaluating if we have enough information about the new feature before getting started

Software development teams often struggle to align themselves on “what” exactly should be developed. Usually, things are done this way: product people come with requirements for the new feature they would like to see. Then, developers implement it, and testers ensure there is no defect and the business requirements are met. 

It looks like the Chinese Whispers game, isn’t it? Like in this game, what we have at the end of the chain is not exactly what we were expecting. That leads to bewildered product managers, a global climate of confusion and defiance, and wasted money and time.

Well, happily, there are ways to build a shared understanding of what needs to be done. This is -for the whole point of behavior-driven development.

In this blog post, I will present a workshop I particularly enjoy for its easiness and efficiency: example mapping. 

Yet another “mapping” thing again

A lot of teams already discuss the requirements of a new feature before the development starts. For example, during planning poker, three amigos sessions, or dedicated discovery meetings, for instance. 

Unlike these free-form meetings, the point of example mapping is to structure this conversation concisely and powerfully, using concrete use cases of the new feature, known as “examples”

Using examples as the starting point of the conversation has multiple benefits:

  • Get a foundation to write your acceptance tests. By reformulating your examples, you will get a set of acceptance tests that will help drive the development of the current user story.
  • Capture the business rules that summarize a bunch of examples
  • Split the current user story into smaller pieces. So your team can focus on a minimal increment and thoroughly prioritize the backlog
  • Reveals yet-to-be-determined behavior or so far unknowns that need to be addressed before starting the development

But how do you run an example mapping session, concretely? 

First, gather the three amigos: product manager/owner, developer, and QA engineer. Diversity in points of view and skills will help you have the most fruitful conversation. Give everyone a pack of colored index cards (or sticky notes) and pens, set a timer to 20~30 minutes, and you are all set. 

For remote teams, collaborative whiteboard tools like Miro will do the trick.

  • Start by writing down the summary of the user story on a yellow card and ensure everyone gets what the expected value of this increment is and to whom (which persona) it is for 
  • Capture examples that illustrate the different behaviors of the new feature on green cards
  • Use blue cards to group multiple examples under a generic rule
  • When questions raise potential impediments in the development of the new feature, capture them on red cards
  • You will often find out that the user story is not focused enough on a small value increment. In that case, break it down using other yellow cards. 

After a while, your example map will look like this:

Example mapping session

The “typology” of the map should give you a few hints about whether you are ready or not to work on the user story:

  • Lots of red cards (questions): the US is not ready to be developed, and you need to learn more before doing it
  • Lots of blue (rules) or green (examples) cards: it looks like the US is too complex and should probably be broken downs
  • A moderate number of rules (5 max) all illustrated by a few examples. Check with the participants, but it is a good sign that you are ready to start developing this new feature.

A return of experience

I discovered this workshop when working with the Cucumber team back in 2019. The whole development team quickly bought it as the benefits were immediate: more focused increments, better alignment of the team members, expected features were delivered more quickly, and so on. I also introduced it when I joined the Gravity team, and it helped us stay focused on our core value proposition. 

After a few years of practice, here are a few tips I figured out along the way that should help you facilitate this workshop with your team:

Keep it short

Example mapping triggers an intense conversation, and the participants will quickly be exhausted. Set a timebox for 30 minutes. After some practice, we are now able to make it in 20 minutes. If you feel like you are close to finishing, suggest taking a few extra 5 minutes to conclude.

Have a facilitator

When the conversation flows, it becomes easy to forget to capture examples, rules, and questions. When running this workshop, we always have one person ensuring everything is noted on the cards. The facilitator also timeboxes the conversation and handles all the logistics (book a room, invite people…). 

Plan it right

When should you plan this workshop? Too long before, and people will forget why behind some rules and examples. Just before development begins will make you have a tough time gathering enough people for a last-minute meeting (and you will have to postpone the development of the user story). Here at Gravity, we try to refine a user story around a week before development starts. In a former team, we used to have two time slots in the week dedicated to example mappings, so the discovery work was done ahead of time. 

Focus on examples

Using concrete examples as the basis of the conversation is a powerful way to challenge the behavior of the new feature and imagine how it will look in the hands of our users. Unfortunately, it is not as natural as we imagine, and I often see participants talk generics first rather than specifics. The problem with generics is that everybody in the room can have their own understanding of it, which is not quite the purpose of the example mapping activity. Encourage people to tell stories, using real-life data to illustrate them (for example, use actual people’s names instead of “the user”) or even draw their examples (which can be far more efficient than natural language in some cases)

Expand the framework

Don’t limit yourself to the four types of artifacts I discussed above (user stories/rules/examples/questions). For example, during these sessions, it is common to discuss technical or UX details related to the behavior of the US. In our case, it frequently happens when we discuss new features involving the data we collect for Gravity and how their format could be impacted. This is why we introduced “Tech rules” and “UX rules” in our example mappings workshops.

Keys for a good example mapping workshop

This article is just an introduction to example mapping. If you want to give it a try with your team, there are plenty of resources on the web. Here is a short list of those:

Stay tuned!

Smoke Tests

Smoke Tests: What is-it?

Testing Gravity

Définition Smoke tests are, according to ISTQB definition:  A test suite that covers the main functionality of a component or…

Product Update - March 2024

Product Update – March 2024

Gravity News Gravity Gravity

Hello! 🌸 Spring has arrived with its share of good news: including our Product Update!! The features we’ve been talking…

Coverage requirements

Combining Usage and Requirement Coverage for Higher Quality

Gravity Testing Gravity

Requirement Coverage in a Nutshell Requirement coverage is a crucial metric in software testing that gauges the thoroughness of the…