Collaborating on requirements with example mapping

Where we follow a team who make some fundamental discoveries in a short time using Example Mapping.

I wrote about the mechanics of example mapping a little while back. A bit like a rule book for the collaborative game it is. But I did not talk about what can happen during such sessions. What we should listen for and what we can learn. I think the best way to do that is by telling a story.

This is a fictional story based on real experience from facilitating and participating in example mapping sessions.

Since I’m bad with names I will assume you are too. So I’ll give you the cast up front:

• Andrew - a senior librarian and domain expert
• Simon - a skilled UX specialist
• Lucia - a skilled software product manager
• Owen - a junior software engineer
• Charlie - a middling software engineer
• Eunice - a senior software engineer

Simon and Lucia have worked together on several software products in the past and know they work well together. Simon is a friend of Andrew’s.

Eunice, Owen and Charlie have worked together on several projects. They enjoy it a lot, and they always work with Extreme Programming.

The story begins

Our story starts at an independent library. They have been talking about creating a digital reservation system for ages. A few months back they finally decided to get started. Andrew, one of the senior librarians, brought in Simon, a UX-er he knows, and Lucia, a product manager that Simon has worked with before, to help them navigate the complexities of software and usability.

The two have now been doing user research, requirements gathering, and other such things for two months. The library staff have seen the suggested solution and really like it. The library patrons too. Being able to reserve a book from home in the morning and pick it up in the afternoon when they are in town is brilliant.

Now they just need to find some software engineers that can code the thing. After some pondering Lucia remembers that there is a local engineering team who are well liked and have done many local gigs. Among them the online ticketing system for both the cinema and theatre. Software that both the staff and the patrons find really easy to use. And so Eunice, Owen, and Charlie are hired.

After about a week of getting their heads around the domain, the existing technology, the UX, and the requirements such as they are presented, the three engineers see that a lot of detail is missing. And the six user stories Lucia presented are huge.

Eunice, Owen, and Charlie want to see things done in very short cycles. And stories that create value done in only a few days. So Eunice suggests that they go through the stories again to break them down further. After some work they have managed to split each of the six stories into far smaller stories. There is still a lot of unknowns, but at least it is now possible to reason about each without getting lost in a maze. Together, the engineers, Lucia, Simon, and Andrew prioritise them. And the story they all think is most important is:

As a patron
I want to reserve a book
So that I can pick it up later that week

Eunice suggests that they come together for an example mapping session. Lucia, Simon, and Andrew look a bit puzzled, so Charlie quickly explains the mechanics.

The first example mapping session

Lucia writes the story on a yellow stick:

Reserve a book

She then goes on to walk the group through the acceptance criteria, whilst Charlie writes them on blue stickies:

• The patron needs to have a library card to reserve a book
• The patron cannot reserve a book that the library doesn’t have
• The patron must pick up the book the same week it was reserved
• The patron can only reserve a physical book, digital books are not picked up

Owen immediately asks if the fact that a patron needs to have a library card shouldn’t be its own story. Surely nothing that has to do with borrowing or reservations will be visible to anyone who has not logged in with their library card. Meaning that as long as that story is done, all others can assume it is so. Andrew nods his head and Simon says that he hadn’t really though about it that way. It’s kinda obvious, but since it’s something that kept coming up as a precursor to all conversations about requirements before, they had just added it into all of them. Lucia writes “Authenticate patron with library card” on a yellow sticky, places it to the side, and removes the first rule.

Eunice asks Andrew and Simon how they see a patron getting to the reservation screen. Simon pulls out some UI mockups that shows the steps from searching for a book, finding a list of results, looking at an individual book, and from there clicking a button that takes them to the reservation screen.

“But are books the library doesn’t have even listed in the search?” asks Charlie.

“No, they aren’t.” Andrew replies.

“Then the patron cannot click on reserve for books the library doesn’t have, can they?” says Charlie.

Lucia removes the rule, shaking her head and silently wondering if she was asleep the day they discussed that particular one.

Eunice pulls a green sticky and writes:

A patron reserves a book on Monday
Comes in on Sunday
–> The book is waiting for them to be picked up

She places it under the rule about picking up reserved books the same week, and pulls another green sticky and writes:

A patron reserves a book on Monday
Comes in the Monday after
–> The book is no longer reserved

Then she says “That’s all good and fine, but would it not be simpler to just make a rolling seven-day rule. Is that a problem from a domain perspective?”

Andrew replies “Yes. The plan is to sort the book by patron to make it easy for them to find their book. If we do that we have to find books all over the pickup point each day. With this solution we can just start Monday morning with returning all reserved books to their shelves. And it’s easy for patrons to find their books, they are under their name.”

Eunice answers “Well, that makes a lot of sense. Then we make sure the rule follows a Monday to Sunday rhythm. We should create a component for this. one that is easy to change. I’m thinking a value object. Something that encapsulates relevant week info. Then we can create a service that runs on a schedule to un-reserve books. What do you think Charlie and Owen?”

“Sounds good,” they both reply.

Eunice moves on to the last rule, asking “What does the system that provides us with info on the book look like? Does it make a difference between digital and physical books?”

Andrew answers “Well, kinda. It’s a flag in the database. But it’s not mandatory so there are places where it’s not filled in. I think all the empty ones are books we’ve had since before we started with digital books though. But it’s possible to cross reference with the ISBN database. And that data is from the publishers so it’s always correct. That’s how we check when we’re unsure.”

“Oh,” says Eunice, “Hmm, I’m thinking we should cache that information in our database so we know then. It’s important logic for when to show the button and not. To me that sounds like a spike, and another story. One about showing the reservation button, rather than making and holding the reservation. Anyone disagreeing?”

Everyone agrees, it makes sense to separate the two. Eunice pulls another yellow sticky and writes

When to show the reservation button.

Andrew asks “How hard would it be to feed that back into our systems? It would be nice to not have to look in two places to find out if something is digital or not.”

“Put it on a wishlist somewhere, it’s out of scope for reservations.” answers Lucia.

Owen says “Well, I don’t think it would be that hard once we have done the references, but it’s an extra and unrelated to this.”

“Sounds like we are done then,” says Lucia, “with this one. But now we have three stories instead of one. On the other hand, each are so much clearer. Thanks for introducing this method. It’s really powerful.”

Charlie says “Sounds about right, I think this one is ready to start work on, but I’m thinking we should spike out the paper or digital book thingy first, what do you think?”

Lucia agrees.

So in 15 minutes the team has ironed out the details of one story, created two new ones, and decided what’s the most important step to move forward.

The second session

The team reconvenes the morning after. The engineers have figured out what the data sources look like and know how often they update. So it’s time to start looking into the two types of publications the library has, physical and digital. Lucia has, in the meantime, come up with a story:

As a patron
I should only see the reserve button
If I can reserve the book

She has also added one rule:

Only physical books should show the reserve button

Lucia puts the story on a yellow sticky and the rule on a blue one.

Andrew says “Well, I don’t know if this is important, but it’s not only books we’re talking about here. As physical items we have paper books, audiobooks, console games, magazines, scientific papers, music CDs, vinyls, and other things.”

Simon says “I remember we talked about this before, you brought the same question up then. Yet we stuck with the term book. Is that not a good term? Should we change it?”

“I think,” says Owen, “it will be quite confusing for an engineer who is trying to understand the code and its relationship to other systems if we only refer to books. When we looked into the other systems there were a whole host of different formats, both digital and physical. I think we should find a better name for this. It’s an important anchor into the wider domain of the library. It would be easy to get lost if the reservation system only talks about books when all other systems talk about all sorts of stuff.”

“Hmm,” says Andrew, “how about we call it something like physical medium. All the things I mentioned are after all information media. And they can be either physical, meaning you have to pick them up at the library, or digital, meaning you need to get them through the app.”

“How about we call it reservable medium then. We are talking about reservations after all. And as far as that’s concerned the medium doesn’t matter, only that the patron can reserve it.” says Lucia.

“Or just reservable item perhaps?” says Charlie.

Eunice holds a hand up to stop the conversation. “The name is important, but I think we can work it out later. For now, let’s go with reservable medium. Names have a lifecycle of their own. But right now we need to look closer at what this reservable thingy actually is. I noticed a couple of things in the other systems that made wonder if digital is the only thing we need to worry about. I found stuff like reference literature. I think there are more rules here.”

“You’re absolutely right” Andrew says. “Other than digital media, this system should not allow for reserving reference material, nor should it allow for the latest two issues of a magazine. Both can only be read at the library.”

Lucia rewrites the rule to read:

Only reservable media should show a reserve button

“OK, now we’ve debated the name, how about we figure out what a reservable medium is?” she asks.

Andrew takes a green sticky and says, whilst he writes:

The media is digital
–> the button is not shown

Then he asks “Is that how we do the examples?”

“That’s perfect” says Eunice.

So Andrew continues

The media is part of the reference library
–> the button is not shown

The media is an issue of a magazine that’s older than the last two issues
–> The button is shown

The media is physical and that is not of the above
–> The button is shown

“OK, I think that’s all the examples I can come up with” says Andrew.

“Hmm, ok, so, are there any other formats that we haven’t covered here?” asks Eunice.

“I don’t think so, and if there are we will simply have to explain to the patron why the system was wrong” says Andrew.

Owen replies “We could look at how to make this changeable as well, I’ll make a story for it so we don’t forget” and writes a story card.

Charlie looks at the time, “We’ve got 5 minutes left. Are there no other rules we should add here? I can think of one. It should not be shown to users who don’t have a library card”. He writes it on a blue sticky.

Andrew looks thoughtful, “I think there is another one, there’s no point to reserve something that’s not available unless we also create a way for people to queue.”

“Ah, yes, we talked about this before,” says Simon “and we decided that it would be nice to have but that it would not go into the first release.”

Andrew writes a blue sticky for the rule, and the timer goes off.

“Well, we learned a lot this time,” says Lucia “let’s do the last rules tomorrow”.

“Sure, sounds good,” says Charlie “we can start to spike out a solution for caching this, now that we know all the different rules we should look for.” Then he pulls a pink sticky and writes:

How often do media change between what is classified as reservable and not?

“It would be good if you could ponder that as well until tomorrow. Given the rules around magazines it’s not clear. It’s easy enough to deal with in the spike, but we need it to complete the story” he says.

What did we learn from this story?

We will now leave the library and the team to continue their work. Instead, it’s time to look a bit closer at some parts of this conversation. When I facilitate or take part in conversations like this I continuously listen for terms that seem important. That I can use as part of the software design. This makes it possible to tease the code apart. Making sure that different concerns, reasons to changes, are not mixed together. The conversations above is where this work starts. But as we learn more, through talking and coding, we continue to refactor the code to match our current understanding.

Let’s start in the first session, with Owen’s question about library card holders. If you take a second look at each the acceptance criteria listed and think a bit about the examples needed to clearly define the boundaries of each. To me, each criterion is rather complex. Each probably containing several rules. At least at a glance. Also, some, like the library card one, is closely linked to authentication and authorisation. Whilst others, like how long a reservation lasts is far more clear and self-contained. It’s a really good idea to split such things into several different stories, let alone different parts of the code. Which is exactly what Owen starts doing.

A bit further on, after the two examples, Eunice talks about software design. She identifies a value object and a service. Both are tactical design patterns from Domain Driven Design. Sure, this may be a bit technical for the forum, but it’s important modeling for the engineers. And the terms used during the conversation will be used when writing the code. These are important building blocks of the ubiquitous language the team is forming during these conversations.

As Eunice and Andres moves on to what books can be reserved and not they discover a can of worms. Eunice suggests a spike, a common extreme programming pattern. In a spike the engineers, and sometimes also others when needed, set aside some time, timeboxed, to figure out how to do something. We use this to uncover unknowns. The timeboxing is important since it provides the product manager with an opportunity to budget the research. And the research is important for the engineers to be able to tell if something is possible or not. Given the current situation a half day spike is a very good way to uncover the complexities already hinted at in the systems they need to integrate with. And there is little point in trying to guess on rules and examples before the team knows what they have to work with.

Another important thing with spikes is that whatever happens in a spike stays in a spike. A spike is never mainlined into the production code. It’s purely a place to learn. This is to ensure that once we know we can do it properly.

As Eunice highlights, when they talk about what to name the reservable item, names have a lifecycle of their own. There is a brilliant series of articles about names over at the Deep Roots website. And if they are going to figure out the correct name now, they will spend hours. And the workshop has an upper time limit of 25 minutes.

Lastly, I’d like to highlight Charlies last question. The day before they though this was just about digital and physical books. Now they have uncovered many different formats. Some that has rather intricate rules for when they are reservable and not. There are probably a few more stories here. Perhaps even some scope limiting options. Should they start with just books in the initial release and add other things later? When we have these conversations we often find that we can slice stories into smaller parts. We also find that we can release some of the parts before other parts. This means we can deliver value sooner. And we can experiment more. It makes it possible to release a medium, check if it’s reserved, and if it’s not we can remove the code again. Decluttering the software and minimising unused and dead features. One of the most common sources of technical debt.

If you want to apply this in a regulated environment there are a few more things you also want to talk about during these sessions. To learn more about that I recommend you head over to Ready to Release which goes into detail about compliance specifically.