Example mapping is a collaborative technique for discussing requirement details. It is typically used to discuss the details of a user story at a sprint planning or sprint planning preparation meeting. In an example mapping session, we break down the user story to rules (acceptance criteria), then illustrate and understand these rules using examples. The story, the rules and the examples are written onto index cards or sticky notes which make the example map. The technique was described by Matt Wynne (there is a good overview about it in Matt’s blog post) and we also discuss it in detail in our book with Seb Rose (Discovery: Explore behaviour using examples; BDD Books 1).

A common question I receive when people try out example mapping is whether there is a way to make sure that we have discussed everything or with other words that we haven’t forgotten about anything.

When discussing the requirements using example mapping, we generally have two goals. First, checking the correctness of the requirements, so that they are understandable and make sense; and second, reaching completeness, which means we have discussed every relevant detail that might be required during implementation. While checking correctness is a goal somewhat easier to achieve, unfortunately there is no method that would guarantee you completeness. However, practice shows that example mapping is a pretty good technique to significantly reduce “forgotten” things.

In order to help discovering the areas of the problem domain, example practitioners sometimes use different questioning techniques, because unless the team is very mature, questions like “Does anyone have any question?” or “Is this clear?” typically does not help you enough.

I use the following techniques, once we have discovered one or two examples for a rule and I would like to make sure that there is nothing more in it.

• Challenge data
• Challenge context (preconditions)
• Positive/negative example
• Find additional outcomes for the same context
• Find different contexts that lead to the same outcome

1. Challenge data

Challenging data means that we look at the data (dates, numbers, names, etc.) in the existing examples, and see if a change in the data leads to a different behaviour. (It is much easier to do this if our examples contain real data.)

For example if you have an example for giving 10% discount for a book with a concrete book that costs 40 EUR (the discounted price is 36 EUR in this case), you can think about what happens if the calculation would lead to a rounding problem for that particular currency. Using a book with original price of 39.99 would be a good example for this.

If you have a date in the condition, e.g. the documents have to be submitted by 1st May, you can discover more information on how the system should handle such deadlines, by constructing an example when someone uploads the documents right before midnight, but from a different time zone.

If you have names or labels in the examples, you can think about their length or whether they should be treated case-sensitive or not.

Obviously with the existing domain knowledge of the team, you don’t necessarily have to play through all of these, e.g. if the team has a general agreement on currency rounding that is clear to everyone, it is not necessary to discuss that case or add new examples for it. But when discovering new areas of the system, this is definitely useful.

2. Challenge context (preconditions)

Although the examples we collect during example mapping are lightweight and not over-formalized (usually just a few hand-written bullet points on an index card), they should have a clear separation of context, triggering action and outcome. I usually underline the triggering action and make an arrow in the front of the outcome, but any format would work.

If you have an example, with a couple of items in the context, you can discover new areas by one-by-one questioning them and see what the expected behaviour would be if we would change them or leave them out.

For example, if you have described an example for the ordering process where the user has logged in, you can have a discussion on how the behaviour would be different with not-logged-in users. Do we show them an error? Do we ask them to login at some point? Should we even allow ordering for non-logged-in users? These are all interesting questions to discuss.

3. Positive/negative example

The examples are primarily used to understand the behaviour related to a rule (acceptance criteria). Obviously the team will focus on the “happy path” cases primarily, because these are the ones that provide value to the customers. However, the implementation costs of the “happy path” are often just a small portion of the total efforts and a lot of time is spent on all the other questions like error handling or special cases.

Finding both positive and negative examples might be helpful for discovering the area outside of the happy path. For example if you have described an example of a successful registration process, you can think about what happens when the user fails with it. Do we show then an error message? Shall we detect a flood of registration attempts generated by a malicious program? Shall we offer an easy retry without filling out all the details again? Is it possible that our ZIP code validation is too strict and does not allow customers from a particular country? How do we detect this?  Sometimes you can find really good things by answering these questions and in some cases you can even turn a non-valuable path for the customer to another one that provides value in the end (e.g. by offering a retry).

4. Find additional outcomes for the same context

Once we have found a useful outcome for a particular situation, we are sticking to it and do not realize that there is more to discover there. Thinking explicitly about additional outcomes might help to see the problem a bit out-of-box.

For example, if we have an example of a successful ordering process with the outcome of a success message and the recorded order, we can think about also sending an email with a promo code for the next purchase. Offering the retry for a failing registration process is also an additional outcome that we could have discovered this way.

5. Find different contexts that lead to the same outcome

This technique is the counterpart of the previous one. With an example with a concrete outcome, we can think about whether the same or very similar outcome should be observed with different contexts. This can help to generalize the problems and better focusing on the intentions of the outcome (rather than the mechanics). For example, if you have an example that sends an email to the user as an outcome, you can think about where else we send emails. Shall we send the email in the same way? Is there a general notification system that handles that? These questions can help identifying components of our system, but they also help to avoid over-specification. If we have realized that we have (or need) a notification system, we don’t have to describe its behaviour for every single example. Think about validation: do we need to describe how a range validator works for all the fields that need such?

Wrap up

These techniques trigger discussions. Often the discussion ends in a way that we realize there is nothing more to add. This is absolutely fine: our goal is not to establish an example-generator. If we discover something interesting, we can still decide what to do with it. We can phrase them as a new example, we can promote it to a new rule that we are going to discuss later or we can even turn it into a question if we need further information to make a decision. In some cases we can even find a great new extension to the feature we are working on, which we do not want to include into the scope of the current user story but we rather put it into our backlog for later.

---

Should you be interested in deeper knowledge in this field, learn more about the BDD Vitals course delivered by Gáspár Nagy.