We build software to help people - the users and customers - reach their goals. This is the only way your organization can get what it wants: revenue for for-profit organization or a measurable impact for non-profit organizations.

To build quality in software, we employ a variety of practices as Test-Driven Development and Continuous Integration. These practices are great to limit the number of defects in the code but them solely don’t guarantee that the built software reflects the domain concepts of the business neither that it helps people reach their goals. It is too easy to build the wrong software.

That’s why the Agile methodologies includes practices that improves communication and collaboration. As example, Scrum has events like the Daily Scrum, the Sprint Planning and the Sprint Retrospective. Extreme Programming has Whole Team and System Metaphor. Both methodologies uses Iterative Development, not just to deliver working software frequently, but also to prove the value hypothesis of the delivered software. These practices are based on the Agile Manifesto principles to reduce the risk of building the wrong software.

Delivering working software that makes people happy does not mean that the team is building shared understanding neither that the software design have the concepts of the domain where it operates. And here comes a critic to my fellow developers, one that I hear often: in the urge to develop a requested feature, we skip conversations that helps building shared understanding of the business in favor to technical discussions.

This critic is beneficial because it shows that the business people are interested in building this shared understanding, that they are incorporating the Agile Manifesto principles. But we are jumping straight to implementation, losing an opportunity to learn the domain and to model the software with the concepts of the domain. Eric Evans (2003) goes further:

(…) if programmers are not interested in the domain, they learn only what the application should do, not the principles behind it. Useful software can be built that way, but the project will never arrive at a point where powerful new features unfold as corollaries to older features. (Evans, 2003)

How to motivate developers to be more aware of the business domain? I think User Story Mapping can come to the rescue.

An early User Story Map from Wikidu (wikidu.com)

User Story Mapping

User Story Mapping is a pattern discovered by Jeff Patton that help teams understand a whole product or feature, with the goal of building a better product:

Story mapping keeps us focused on users and their experience, and the result is a better conversation, and ultimately a better product. (Patton, 2014)

The outstanding documentation that Patton created shines a light in how stories1 are being misused, making teams to fall in one or more traps. I highlight two of these traps:

  • The flat backlog: stories let teams focus on building small things, losing sight of the big picture. It often results in Frankenstein-like products, where the products seems assembled from mismatched parts
  • Form over substance: when the focus from writing stories is only to get them written instead of building shared understanding

I’ve included a crash course to better explain how it can help motivate everyone to build shared understanding. You’ll need sticky notes, pens, a tabletop and a wall (or a whiteboard).

The backlog column don’t show the big picture of this product

Crash course

Set a timebox (10 minutes at maximum) and ask people to start writing in silence the tasks that the users will make in your application. These users tasks are things like “Request a ride”, “Rate the book”, “Add product to cart”. Once everyone finished, ask people to read each sticky note and place it in the tabletop. If duplicates are found, remove them. In summary, the steps are: think, write, explain and position.

You’ll find some interesting things during the process:

  • Most sticky notes will contain short verb phrases
  • People will organize the tasks intuitively in a flow order, with tasks that must happen first in the left side with later tasks following them
  • Some sticky notes will contain tasks that happens around the same time as other tasks. These are subtasks. In a software application these can be additional and/or optional steps the user can take

Now that you identified the user tasks, it is time to organize your map. Intuitively some of this work was already done: tasks that must happen first are placed in the left side, with later tasks following them. Stack the subtasks below their main tasks.

To validate if this flow is consistent, start telling the story of your map: point to the first user task saying “First the user does this”, and then pointing to the next saying “and then it does that” until the last task.

This is what Patton defines as the “narrative flow” or the “storytelling order”. Reorder the tasks placement if the narrative seems awkward. You’ll also find missing details because the map helps you to see the big picture. Fill the missing details as you go.

Prove the consistency of your map telling its story

The next step is to distill the map. Step back and pay attention to the narrative flow. You’ll find that there are clusters of tasks that goes together. The ecommerce user tasks, “Add to cart”, “Estimate freight” and “Checkout cart” could be grouped in an “Place an order” activity. For a social network, “Search by name”, “Visit the person profile” and “Add as a connection” could be grouped in an “Connect” or “Friend” activity.

Write the activity name in a sticky note and place it above the cluster of tasks that it defines. Validate if the narrative flow is still consistent, reading the activities in the same manner as you had read the user tasks. The activities forms the backbone of the map.

The backbone of the map is formed by the activities

Adding context to the map

A map can have more than user tasks and activities. You can add any meaningful information to it, helping to build shared understanding:

  • Opportunities and hypothesis. Why build it? What kind of problem it solves?
  • Product principles. Examples: fun, easy, accessible (hey, this should be a principle of any product, period), friendly, fast
  • Customers and users. Who are my users? What are the different users roles? Why they will use the product? What do we think about them? What types we will prioritize now?
  • Details, options and questions. More details about the tasks and activities can be provided as well different options. If someone is not sure how something will work, it can place sticky notes with doubts. Notes about how other services - competing or not - solved some issue can also be placed in the map.

You can use sticky notes of different colors and place this information where it is meaningful to give more context.

Enrich your conversation adding more context into the map

Building shared understanding is the key

What is really important during the creation of the map is the shared understanding built by better conversations. This is the original idea of stories when introduced by Kent Beck: to turn the focus from shared documents towards shared understanding.

Just writing stories as shared documents don’t help to build shared understanding because when someone reads a story, it can interpret it in a different way than the story’s author. This is only possible when we externalize our ideas. The written story then becomes a mean, not an end.

How can this motivate technology-driven developers?

As a developer, I know a lot of things that can make developers less concerned about the business. One of them is the absence of product vision, the lack of the big picture. Roadmaps are constantly created to provide this big picture but usually they are not visual enough or updated often to radiate clearly where in the journey the team is. And the flat backlog can give an impression that the only work the developers must do is to process new stories.

The developers become alienated from the business goals and thus lose interest in the domain. And as developers like to build things, it is easy to turn the attention to the technology side and solve domain problems with technology (Evans, 2003).

As a visual tool, a map can clearly radiate information about the big picture. It can be used to prioritize the stories to be worked out (Patton explains prioritization techniques in his book). It is a living roadmap. The developers can understand better what and why they are working and how that fits in the big picture.

Asking developers to help create the map (I think the first map should be created with the contribution of the whole team) can provide not just different points of view but also interesting and valuable ideas (developers tend to be early adopters of all kind of technologies, from mobile apps to wearables). And then they start to ask why/what/how: now they’re not just helping to build shared understanding, they are willing to learn about the business.

Creating the map can also build stronger relations between team members and develop values like respect and courage. If the team goes further to try to understand the users/customers better and create personas2, it can develop empathy by the users in the developers. Stronger relations between the team, more awareness about the business goals and more empathy for the users can unlock one of the three elements of motivation: purpose (Pink, 2009). Purpose is the yearning to do what we do in the service of something larger than ourselves. People who find purpose in their work unlock the highest level of the motivation game.

Map to help with your DDD adoption and to produce an Ubiquitous Language

Evans’ Domain-Driven Design (DDD) book introduced a new approach to software development that places the focus in implementing a software design based on a model of the domain. It can help reaching a point where the design is exactly how the software works (Vernon, 2013) by giving strategic and tactical modelling tools necessary to design high-quality software that meets core business objectives .

As an approach, DDD is not about technology:

DDD is about discussion, listening, understanding, discovery, and business value, all in effort to centralize knowledge. If you are capable of understanding the business in which your company works, you can at a minimum participate in the software model discovery process to produce a Ubiquitous Language (Vernon, 2013)

To build a domain model and effectively adopt DDD, it is needed to crunch knowledge. “To centralize knowledge” is a synonym of “to build shared understanding”. Evans says that effective domain modelers are knowledge crunchers and emphatize that this is a team activity (and a requirement to practice DDD):

Knowledge crunching is not a solitary activity. A team of developers and domain experts collaborate, typically led by developers. Together they draw in information and crunch it in useful form. The raw material comers from the minds of domain experts, from users of existing systems, from the prior experience of the technical team with a related legacy system or another project in the same domain. It comes in the form of documents written for the project or used in the business, and lots and lots of talk. Early versions or prototypes feed experience back into the team and change interpretations. (Evans, 2003)

From this knowledge crunching, the team (developers and domain experts) must develop an Ubiquitous Language, which is a shared language. The vocabulary of this language is centered in how the business itself thinks and operates (Vernon, 2013) . This shared language prevents misunderstanding between the business people and developers by removing the need of translations between business concepts and the abstractions used in the software design.

The Ubiquitous Language is one of the pillars of DDD alongside Bounded Context (Vernon, 2013) . Its vocabulary includes names of classes and prominent operations and is the the primary carrier of the aspects of design that don’t appear in code (Evans, 2003).

That’s where Story Mapping can help your DDD adoption. It is a great technique to start the knowledge crunching process and to produce the initial glossary of the Ubiquitous Language. Make it a collaborative effort: it will help to form your team and will push them to have the required conversations.

Map to assess your domain complexity

In Implementing Domain-Driven Design, Vernon presents a scorecard3 to help teams to determine if it is worth to adopt DDD in a project. If you get a score of seven or higher, consider the adoption of DDD.

If your project Points Supporting thoughts
If your application is completely data centric and truly qualifies for a pure CRUD solution, where every operation is basically a simple database query to Create, Read, Update, or Delete, you don’t need DDD. Your team just needs to put a pretty face on a database table editor. In other words, if you could trust your users to just insert data directly into a table, update it, and sometimes delete it, you wouldn’t even need a user interface. That’s not realistic, but conceptually relevant. If you could even use a simple database development tool to create a solution, don’t waste your company’s time and money on DDD. 0 This seems like a no-brainer, but it’s not usually that easy to determine simple versus complex. It’s not like every application that isn’t pure CRUD deserves the time and effort of using DDD. So maybe we could come up with other metrics to help us draw a line between what is complex and what is not…
If your system requires just 30 or less business operations, it’s probably pretty simple. This would mean that your application would have no more than 30 total user stories or use case flows, with each of those flows having only minimal business logic. If you could quickly and easily develop such an application using Ruby on Rails or Groovy and Grails and not feel the pain of lacking power and control over complexity and change, your system probably doesn’t need to use DDD. 1 To be clear, I am talking 25-30 single business methods, not 25-30 whole service interfaces, each with multiple methods. The latter might be complex.
So let’s say that somewhere in the range of 30 to 40 user stories or use case flows could be creeping toward complexity. Your system might be getting into DDD territory. 2 Caveat Emptor: Very often complexity is not recognized soon enough. We software developers are really, really good at underestimating complexity and level of effort. Just because we might want to code up a Rails or Grails application doesn’t mean we should. In the long run those could hurt more than help.
Even if the application is not going to be complex now, will it grow in complexity? You may not know this for sure until real users start working with it, but there is a step under Supporting thoughts that may help uncover the true situation.

Be careful here. If there is any hint at all that the application has even moderate complexity—here’s a good time to be paranoid—it may be sufficient indication that it will actually be more than moderately complex. Lean toward DDD.
3 Here it pays off to walk through the more complex usage scenarios with domain experts and see where it leads. Are domain experts…

(1) already asking for more complex features? If so, it’s likely an indication that the application is already or will soon become too complex to use a CRUD approach.

(2) so bored with the features that they can hardly bear discussing them? It’s probably not complex.
The application’s features are going to change often over a number of years, and you can’t anticipate that the kinds of changes will be simple. 4 DDD can help you manage the complexity of refactoring your model over time.
You don’t understand the Domain because it’s new. As far as you and your team know, nobody has done this before. That most likely means it’s complex, or at least deserves due diligence with analytical scrutiny to determine the level of complexity. 5 You are going to need to work with domain experts and experiment with models to get it right. You certainly also scored on one or more of the previous, so use DDD.

After finishing your map, you’ll have the big picture of the product you want to build. Do you remember the user tasks? They are the stories your team will need to develop. Each can have n subtasks or alternative flows. Count the user tasks and you’ll know if you scored in the second or third case. Another complexity indicators are the visual density of the map and the quantity of user roles (and the way they influence the user tasks).

Obviously the map alone can not be enough to assess the complexity of your project. For example, many startups explores business opportunities that fall in the last case. And when a startup depends of a software application for its business, you might expect that its features will change over time to better support the growth and continuity of it. Use the map as one of the raw materials for your assessment.

Closing remarks

User Story Mapping is a simple yet insightful pattern that rescues the original idea of Beck’s stories: to have good conversation for the good of shared understanding. As a collaborative task, it helps in team formation and motivation.

Some Agile practitioners may fear Story Mapping as a big up front plan. It is not meant to be. Build the first map to discover the narrative and then use it to prioritize the stories to be developed. As they approach to be prioritized for development, start the knowledge crunching to identify what you need to learn.

Keep it as a living document and update it every time you discover something new. Update the narrative flow while you validate your value hypothesis. Use the map as your backlog, without losing the big picture!

Curiously, some developers used to Agile software development fear that DDD can lead to a big up front design. My personal belief is that this impression is caused by the emphasis on conversations and on diagrams in the literature. You need to discuss because you need to learn the business principles behind a story. The diagrams are just abstractions, they don’t necessarily reflect the future design: a lot will be left to be discovered and that’s where TDD shines.

Last but not least, Story Mapping can be a valuable input in your assessment for DDD’s adoption. If your project is complex and you adopt the DDD approach to software development, the map can help you start the knowledge crunching process and in the production of the initial Ubiquitous Language glossary.


Thanks to Nelson Senna and Fernando Ike for the proofreading and to Vaughn Vernon for the positive feedback.


  1. I use the noun story instead of user story for convenience. Stories are widely used in Agile methodologies for planning purposes. Introduced by Kent Beck, stories encourage informal conversations for the building of shared understanding. 

  2. A persona is a written representation of a specific user which can be used to make decisions about software features. Patton describes a pragmatic way to create user personas

  3. The full explanation of the DDD scorecard is also available at the InformIT website (content from the rough cut of the book).