Example Mapping for User Stories: Our attempts for its adoption and the lessons we learned
Introduction
All developers, testers, and product owners have been there, gathered in rooms, running meetings while trying to identify and analyse acceptance criteria. During these meetings, the participants hope they can clarify and understand a user story, and if everything goes as planned, by the end of the meeting, engineers can get back to work and start developing. In the real world, that’s far from what really happens on many occasions.
Unfortunately, it’s all too common to have experienced a situation where hidden areas of the user story were later discovered by testers, or even worse during a sprint review.
When important questions remain unidentified till the moment development is about to start, then naturally engineers will realise that they have to ask new questions back and forth with the product owner to clarify answers that should have already been discussed. In these instances, communication very often takes place online through multiple instant messaging apps, emails or through word of mouth, while the testers often may not even have been able to catch up with what has been updated till the user story’s status becomes “Ready to test”. In summary, working in this approach would only increase the chances of making errors and perhaps raising tension among peers.
Before a user story is pulled into development, it is essential to have a structured conversation and expect all participants to remain focused. For myself, while being a part of the software testing team at SCMP, I noticed this was something that was missing from our engineering team, where our initial meetings were unstructured, often too long and made engineers unable to remain engaged. Additionally, our engineering team was newly formed, and the project planned ahead was all new to us. During the initial efforts of identifying acceptance criteria, when a question was raised, it would not always get documented. We often were assuming the acceptance criteria were straightforward, easy to understand when presented and by using common sense things will get developed as expected. That was far from what happened on a few occasions.
From a personal perspective, I have seen these issues occur repeatedly in the past even in companies I worked previously, although I had not been able to figure out a viable solution. Recently though, I came across the technique of Example Mapping and then I immediately proposed its adoption to our team at SCMP. I initiated a presentation and highlighted its benefits and how it could help us. My prime goal was to add structure to our conversations while keeping engineers engaged on each topic discussed during our gatherings. Think about it, if you can achieve everyone to share the same understanding of a user story in advance, that would then improve the team’s efficiency in delivering more frequently working software straight from the beginning!
What is Example Mapping?
Example Mapping is a technique developed by Matt Wynne that aims to add structure to a conversation by breaking down any product backlog user story within 25 minutes. Example Mapping assists teams on how to have a conversation and the areas to cover. it’s that simple!
During Example Mapping, the following areas have to be discussed for each user story;
rules, examples and questions.
- The rules describe what the system should and should not do
- The examples describe where rules take place, that can include e.g. specific events and user roles
- The role of questions is to identify incorrect assumptions or to identify areas that have not yet been explored
What you would need for capturing the rules, examples, and questions is a pack of coloured index cards (yellow, blue, green and red), a few pens and your team. As the discussion takes place the captured rules, examples, and questions are arranged in a map on a table.
The best way to further dive into the details and understand how Example Mapping works in action is by watching the webinar Introducing Example Mapping by Aslak Hellesøy.
The tools we have used for Example Mapping
At the very beginning we started with plain index cards, that was the best way to demonstrate how Example Mapping works. At the time the team became familiar with the process we switched to an app by TEAMUP LABS (which nowadays is a plugin for the issue tracking product JIRA) and on some other cases we used just a spreadsheet with coloured cells. As with every system, the tools are not the most significant aspect. Furthermore, knowing how a system works and having a number of tools to serve you is not enough, what you need is to act. In other words, knowing a theory and not applying it, is not yet to know it.
How Example Mapping added value to our engineering team
Initially, in our newly formed team, we adopted Example Mapping for user stories that involved a significant amount of complexity. What I noticed from the very beginning was that all engineers were more focused and were asking more questions than previously. On some occasions, we also realised that a user story had to be further broken down to multiple user stories (backlog refinement) and in some other cases, raised questions could not be answered by any of the participants. That was because the answers could only be provided by third parties from other teams. On a few other occasions, we happened to realise how little we really knew compared to what we had assumed that we all knew. Eventually, by the end of each Example Mapping session, what we all started shaping was a common, mutual understanding of the user story among all the participants.
The creation of documented examples during the Example Mapping was something very new to me. Previously, what I used to always see in acceptance criteria gatherings were a list of bullet point conditions that were describing what the system should do and not do. I would very rarely see examples. Documented examples, in the form like those given in daily conversations, were completely absent. At times when we participate in a conversation with a person who is trying to describe something complicated, we would naturally often say, “I am sorry, but I am confused, can you please give an example?”. This is the case with the actual role of examples in Example Mapping where it requires participants to really give verbally an example which then it gets documented on a green index card.
With this approach, it makes the given verbal examples and questions explicit and documented. In a traditional setting, normally it would have been assumed that everyone — and based on common sense — had a common domain knowledge and understood how the system behaves. Moreover, engineers would have been expected to remember fine details mentioned previously in conversations till the moment they are seated on their seats and are about to get started with coding.
By the end of an Example Mapping session, when content from the blue, green and red cards is transferred to the team’s issue tracking system they become an invaluable asset that is accessible as a permanent record for all involved parties to retrieve at any given time.
How Example Mapping added value to our testing team
Software testers know how a system behaves very well. They become familiar with every single peculiarity of a system, simply because they need to test all of its features extensively. Because of that, testers are great observers that can proactively provide feedback and constructive criticism on existing procedures, user interface enhancements, and workflows.
I became an advocate of Behaviour Driven Development BBD and its benefits among other engineers who wanted to inspire and make a positive impact. My plan was to streamline the adoption of BDD into our entire workflow (including acceptance criteria, scenarios, test automation and live documentation) and make it work as seamlessly as possible.
During the Example Mapping, the examples were written in a natural english language on green index cards, this allowed our testing team to facilitate the writing of scenarios in the Gherkin language format. For the first time, we were able to collaboratively define the acceptance criteria in a collaborative and effective manner and in a format that was immediately adaptable as cucumber features which we could convert to code functions for our upcoming web automation project. We had started shaping the foundation of BDD, where conversations are the acceptance criteria and simultaneously the documentation, the test scenarios, and the executable code! Yes, all in one, and most importantly defined and understood by everyone upfront!
Within our engineering team, the writing of examples was not anymore just the mere job of the testers, instead, it became a collaborative effort within the entire team. In the testing team, we were able to look at the examples and draft from there the first positive scenarios, while simultaneously ensuring that every single person of the engineering team had a common understanding of the system’s behaviour. At this point, by the end of each iteration, if something had been missed out, it was not anymore due to a misunderstanding of the acceptance criteria. Instead, it was because a feature had not been discussed to become part of the user’s story scope.
Our challenges on adopting example mapping
The most difficult challenge for myself was how to communicate my message across the entire engineering team. Additionally, as with every new idea that brings change, it is expected there would be some form of friction. I decided to conduct a presentation on BDD as well as Example Mapping where I showcased the benefits of Example Mapping and how it could assist our efforts with running BDD effortlessly.
When we were in need to discuss the acceptance criteria of a user story, I took the lead on using Example Mapping in collaboration with our product owner. At this point forward, we were able to start adding structure to our conversations while we all remained focused and contributed on the topics we had to deal with.
After a few attempts of running Example Mapping some engineers were enthusiastic about it. I was getting a positive feedback, they were able to see its value. On the other hand, other engineers had started raising concerns, which some of them included “It is a very slow process”, “It is a waste of time”, “Example Mapping is a process where developers have to do the job of testers, which is to write test cases.”
There were moments I was frustrated, I realised how far away I was from getting my message across effectively communicated. I felt that all my efforts had failed. Not only did I have to improve how to communicate the benefits of Example Mapping, but also I had to re-introduce the core values of BDD and clear of any misconceptions that still existed. Clearly, there was a lot more work to be done from my side and, frankly I was not sure what to do next. I decided to pause for a moment, instead of further pushing Example Mapping, I concluded to take a small break. Well, I thought, if I let the team hit to a point where a serious error happens due to a miscommunication, then they would eventually try to reflect and think about how they can improve their processes. Afterall, mistakes are the stepping stones to learning. And surely again, an error happened due to a miscommunication. At this time, to my surprise, some engineers proactively came to ask for my help to run again an Example Mapping session for an upcoming complex user story, hoping that through the session, the acceptance criteria will be nice and clear for everyone. At our next iteration, albeit Example Mapping was not adopted for all our user stories, things started getting better and we were making progress. The engineering team decided that we could just adopt Example Mapping only for the very complex user stories and use common sense for the trivial ones. I disagreed. I argued that we would rather spend a few minutes in advance to ensure we get a user story commonly understood, rather than to assume that it is a trivial one and, then if a problem occurs we would have to deal with it back and forth in endless communication loops and code changes.
Nowadays, the current situation in our team has progressively improved. Firstly, we started reaping the benefits of the Example Mapping for complex user stories, secondly, the Example Mapping had an indirect impact to our team. The product owner started providing on some occasions written examples under the description of the user stories. That definitely provided further clarity which assisted us to go faster and with more confidence through the entire workflow, from backlog refinement, sprint planning and development.
Conclusion
One thing has become evident to me, the use of examples — either in the use of a formal Example Mapping session or any other form — has the power to shape a picture that would be commonly understood in the exact same way by whoever gets exposed to. In a software engineering sense, by using examples, the engineering team can have a shared understanding about a system’s behaviour.
In photography, when multiple people are exposed to a photograph without a caption, the photograph’s interpretation is relatively subject to the imagination of each viewer, where on the other hand, when the displayed photograph is accompanied by a caption, there will be a shared understanding of the picture’s subject.
Furthermore, verbal examples can provide the same clarity to the development of an engineering project as a dictionary of the english language would do to a writer, which is to clarify what the meaning of the word is with given examples of sentences. Can you imagine a world where dictionaries did not exist and you were supposed to know and remember what each word meant? Commonly, even with the existence of dictionaries human communication is not exempted from errors, because when a speaker knows the definition of a word, there is no guarantee that the other person does, and that is where the trouble starts. For that reason, only when people clearly have a shared understanding of the definition of a word would be able to increase the chances of having a smooth conversation. For example, if ten people randomly are asked of what is the definition of the word “justice”, or “communism” it is very likely that ten different definitions will be described.
In conclusion, among other fields that are prone to errors over human interaction, software engineering is not an exception. In other words, the development of software is also vulnerable to the limitations of human languages as well as of how these languages are being used. This subject area is addressed in the field of the philosophy of language-meaning of general semantics with an introductory reference being the book by Stuart Chase The Tyranny of Words.
Useful resources
Example Mapping Introduction — https://cucumber.io/blog/bdd/example-mapping-introduction/
The Tyranny of Words by Stuart Chase — https://archive.org/details/B-001-018-046/page/n6
