What is Example Mapping?

Example Mapping is a method that uses concrete and precise examples to illustrate and better define a user story’s acceptance criteria. The workshop’s purpose lies in fostering collaboration between business users and delivery team members around the same language.

Agreeing on examples in the domain language contributes to building a shared understanding of the specifications. Developers have an opportunity to bring up edge cases and directly clarify them with business users. Responsibility for proper specifications is shared between business owners or product owners and delivery team members.

In Agile practice, Example Mapping is generally a part of TDD (Test-driven Development) or BDD (Behavior-driven Development). Tests can be directly derived from examples that can be used as living documentation for traceability.

Who should be involved in an Example Mapping workshop?

Although large workshops involving the development team, business stakeholders, and domain experts effectively transfer knowledge and build a shared understanding among the entire team, they cost a lot of time and money. They can be overkill for a mature team that has already built up sound domain knowledge.

That is the reason why running a smaller workshop involving one business owner or product owner, one developer, and one tester is often sufficient to gather relevant insights from different perspectives. This meeting is named The Three Amigos.

How to run an Example Mapping workshop?

Example Mapping uses four types of items:

If you end up with too many rules and examples, it might mean that the user story should be broken down into several smaller ones. Example Mapping is a good way to ensure user stories are always at the proper size.

How to define examples in a way that helps write good tests?

It’s obviously easier to write good tests from the right specifications. That is why a proper example should set the context, specify a single action, and define the expected post-conditions. To do so, you can define an example with the Given-When-Then technique that comes from the BDD:

Let’s illustrate the framework with an example:

Gojko Adzic’s Example Mapping tips

Based on several years of experience and collective knowledge gathered from about 50 projects, Gojko Adzic has summarized a few Example Mapping tips in his book Specification by Example:

Gojko Adzic portrait
Gojko Adzic Software delivery consultant and author of several books on Impact Mapping, Specification by Example, Behavior Driven Development, Test Driven Development and Agile Testing (https://gojko.net/)

Suggested resources to run effective Example Mapping workshops