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.

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.

Example Mapping uses four types of items:

• User story with a yellow sticky note. It is the starting point of the conversation
• Rules with blue sticky notes. They highlight acceptance criteria as requirements or constraints related to the scope of the user story.
• Examples with green sticky notes. They illustrate the rules.
• Questions with red sticky notes. They absolutely have to be answered before considering the user story ready for implementation.

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.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.

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:

• Given a precondition,
• When an action happens,
• Then the following post-conditions should be satisfied.

Let’s illustrate the framework with an example:

• Given a user has exceeded the 500-item limitation,
• And 24 hours have passed since,
• When the user signed in again to the application,
• The user can’t edit any document anymore.

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:

• Examples should be precise. To avoid ambiguities, a good example should clearly define the context and how the system should work in a given case. You should describe something that can be easily checked.
• Examples should be realistic. To do so, use real data when you can use some and get basic examples directly from customers. Avoid abstract users or clients (like “Client A”) and find a real customer who has the characteristic you want to illustrate.
• Examples should be easy to understand. Avoid the temptation to explore every combinatorial possibility, for example, by building tables with dozens of columns and rows. You should focus on precise common and edge cases. Keep in mind that the main goal of Example Mapping is to help the team think about functional gaps and inconsistencies.
• Get precise performance requirements. Characteristics such as performance or response times are called non-functional requirements. Many teams struggle to describe them with discrete answers, which leaves room for either under-or-over quality. You should provide the development team with a clear target for implementation.