Example Mapping: rules, examples, questions
In short: Example Mapping is a short session with four colours of cards: the story (yellow), the rules (blue), the examples (green) and the questions (red). The board shows what we know and what we do not. Many blue cards mean the story is too big, many red ones mean it is unclear.
Problem
The meeting that never ends
The owner, QA and the developer are discussing the discounts story. After an hour, everyone has said something about the promo code, loyalty and discounted products. One question ("what if the order is returned?") has been asked three times and has stayed unanswered every time.
At the end the owner says "the developer will figure it out", and the meeting is over. Nobody has written down what was decided. A week later everyone remembers it differently.
The conversation happened. But nothing of it remained, and nobody saw that the story was too big.
The idea
Four colours
Example Mapping is a short session in which a story is taken apart into cards of four colours:
- yellow: the story. One, at the top;
- blue: the rules. Each rule is a column under the story;
- green: the examples. Each sits under the rule it shows;
- red: the questions. The things nobody in the session knows. They sit to the side.
For the story "As a customer I want to put several items of a product in the cart" the board might look like this:
| Rule (blue) | Examples (green) |
|---|---|
| At most 10 items of one product | 9 in the cart, I add 1: it becomes 10 · 10 in the cart, I add 1: refused, it stays 10 |
| At least 1 item is added | I add 0 items: refused |
| Question (red) | Does the limit apply to discounted products too? |
The cards are small. One thing goes on a card, in a few words. That way nobody makes a speech, and the whole board can be seen at once.
More precisely, if you are curious
The technique was described by Matt Wynne of the Cucumber team in the article "Introducing Example Mapping" (2015). He suggests naming examples briefly, like episodes of a TV series: "the one where Maria pays with the code twice". A name is easier to remember than a table of numbers.
Example Mapping is not in the ISTQB syllabi. ISTQB CTFL v4.0.1 talks about the same idea more generally: acceptance criteria are written together, and examples become acceptance tests (ATDD). Example Mapping is one concrete way to do it.
The idea
How the session runs
Three people take part: someone from the business, QA and a developer. They are often called the three amigos.
- You put down the yellow card with the story.
- You state the rules you already know. Each becomes a blue card.
- For each rule someone asks "give me an example". Each example becomes a green card under its rule.
- When someone says "I don't know", or two people disagree, that becomes a red card. You do not argue. You write the question down and move on.
- At the end you look at the board and decide: is the story ready?
The session takes about 25 minutes. If the story does not come together in that time, that is an answer too: it is too big or too unclear.
Try it
Which colour?
The idea
What the board says
The board shows not only what we know, but how much. A look from above is enough:
| On the board | It means |
|---|---|
| many blue cards | the story carries many rules: too big, split it, often one rule per story |
| many red cards | we do not know yet what we want: unclear, answers first |
| a blue card with no green one | the rule is not understood: nobody can give an example |
| many green cards under one blue one | the rule is complex and may be a story on its own |
| a few blue cards, each with examples, few or no red ones | ready for work |
This is a measure, not a formula. There is no number from which cards count as "many". But when you see five blue columns, you know what to suggest.
Try it
Lay out the delivery board
Place every card: as a rule, as an example under its rule, or as a question. Then decide what the story is.
As a customer I want free delivery on a bigger order so that I do not pay 4.90 € for delivery.
For every card press “Place as…” and choose: a rule (it becomes a column), an example for a rule, or a question. The arrow keys move between the choices, Esc closes. You can also use the mouse: drag the card to its place.
Rules
No rules yet. Place a card as a rule and it becomes a column.
Questions
- No questions yet.
Cards not placed yet
A cart with no products: the order is refused
A cart of 49.99 €: delivery is 4.90 €
Is the 50.00 € threshold counted before the discounts or after them?
An empty cart cannot be ordered
The customer has not paid yet and sees in the cart: "Delivery: 4.90 €"
The customer sees the delivery cost in the cart before paying
Delivery is free from 50.00 € inclusive, otherwise it is 4.90 €
A cart of 50.00 €: delivery is free
The sorted board
- Delivery is free from 50.00 € inclusive, otherwise it is 4.90 €
- A cart of 49.99 €: delivery is 4.90 €
- A cart of 50.00 €: delivery is free
- The customer sees the delivery cost in the cart before paying
- The customer has not paid yet and sees in the cart: "Delivery: 4.90 €"
- An empty cart cannot be ordered
- A cart with no products: the order is refused
Questions
- Is the 50.00 € threshold counted before the discounts or after them?
What is the story? Ready for work. The question about discounts is a single one, and someone can decide it: the owner. Their answer becomes one more example under the first rule, and the work on the rest can start.
Three rules, each with an example, and one question. The question is real: the owner has to decide whether 50.00 € is before or after the discounts. But it does not stop the work on the rest, and the answer will become one more green card.
The idea
A question is not a failure
A red card does not mean the session went badly. It means you found something that would otherwise have come out at release. The question "what if the order is returned?" costs five minutes on the board. The same question after release costs a defect, a fix and an unhappy customer.
The most dangerous card is a question hidden as a rule: "we assume the code does not apply to gift cards". It sounds like a decision, but nobody made it. If you do not know, write a red card.
Every question leaves the session with two things: who will answer and by when. Often it is the owner. Sometimes it is a stakeholder who was not in the room, such as accounting.
Exercise
Boards from the shop
1. The discounts. The story from the start of the lesson.
Place every card, then decide what the story is.
As a customer I want a discount with a promo code and for loyalty so that I pay less.
For every card press “Place as…” and choose: a rule (it becomes a column), an example for a rule, or a question. The arrow keys move between the choices, Esc closes. You can also use the mouse: drag the card to its place.
Rules
No rules yet. Place a card as a rule and it becomes a column.
Questions
- No questions yet.
Cards not placed yet
A loyal customer, a t-shirt for 20.00 €: 19.00 €
Discounted jeans for 40.00 € with AUTUMN10: still 40.00 €
A loyal customer gets 5 % off
If the paid order with the code is returned, can the code be used again?
Maria entered AUTUMN10 but did not pay: in a new order the code works
A promo code can be used in one paid order
A promo code gives 10 % off
Maria has already paid an order with AUTUMN10: in a new order the code is refused
Discounts do not add up: the bigger one applies
A loyal customer with AUTUMN10, a t-shirt for 20.00 €: 18.00 €, not 17.00 €
A promo code does not apply to discounted products
A t-shirt for 20.00 € with AUTUMN10: 18.00 €
The sorted board
- A promo code gives 10 % off
- A t-shirt for 20.00 € with AUTUMN10: 18.00 €
- A promo code does not apply to discounted products
- Discounted jeans for 40.00 € with AUTUMN10: still 40.00 €
- A promo code can be used in one paid order
- Maria has already paid an order with AUTUMN10: in a new order the code is refused
- Maria entered AUTUMN10 but did not pay: in a new order the code works
- A loyal customer gets 5 % off
- A loyal customer, a t-shirt for 20.00 €: 19.00 €
- Discounts do not add up: the bigger one applies
- A loyal customer with AUTUMN10, a t-shirt for 20.00 €: 18.00 €, not 17.00 €
Questions
- If the paid order with the code is returned, can the code be used again?
What is the story? Too big: split it. Five rules for two different discounts. The promo code is one story, loyalty another, and "the bigger one applies" a third, after them. Each can be built and accepted on its own.
Five blue columns for two different discounts. The split is ready on the board: the promo code (three rules), loyalty (one), and "the bigger one applies" after them. This is also the split by business rules from the lesson on splitting.
2. The return. The story about returning a product.
Place every card, then decide what the story is.
As a customer I want to return a product so that I get my money back.
For every card press “Place as…” and choose: a rule (it becomes a column), an example for a rule, or a question. The arrow keys move between the choices, Esc closes. You can also use the mouse: drag the card to its place.
Rules
No rules yet. Place a card as a rule and it becomes a column.
Questions
- No questions yet.
Cards not placed yet
Can a product be returned once it has been unpacked?
Can a single product from the order be returned on its own?
Only a delivered order can be returned
Who pays the courier for sending it back?
Is the delivery cost refunded too?
Received on 1 October, requested on 15 October: accepted
Received on 1 October, requested on 16 October: refused
Returns within 14 days of receiving the goods
A shipped order that has not arrived yet: no return is offered
The sorted board
- Returns within 14 days of receiving the goods
- Received on 1 October, requested on 15 October: accepted
- Received on 1 October, requested on 16 October: refused
- Only a delivered order can be returned
- A shipped order that has not arrived yet: no return is offered
Questions
- Who pays the courier for sending it back?
- Is the delivery cost refunded too?
- Can a single product from the order be returned on its own?
- Can a product be returned once it has been unpacked?
What is the story? Unclear: answers first. The rules and examples for the deadline are clear, but the four questions are about the money and about what can be returned at all. Without the answers the team will decide them alone, by guessing. First the owner and accounting, then the work.
The deadline is clear, with examples right on the boundary: 15 and 16 October. But the four questions are about the money and about what can be returned at all. Their answers will bring new rules, maybe new stories too. So they come first, then the work.
The idea
After the board
Every colour has a next step:
- the yellow card stays the story. Or it is split into several, if the board said so;
- the blue cards become the acceptance criteria;
- the green ones become the examples in the criteria. In the next module each example becomes a Gherkin scenario, and the rule above it becomes the keyword "Rule";
- the red ones go to whoever can answer them. The story waits until they come back.
So 25 minutes give you everything the confirmation of the three Cs needs: the rules, the examples, and a list of what we still do not know.
Test