Skip to content
Carmel Eve By Carmel Eve Software Engineer I
How to enable intra-business communication using user stories, BDD specs and a ubiquitous language

Here at endjin we often work with customers who are struggling to bridge a communication gap between their business stakeholders and the development team. This is a worldwide, cross-industry problem as the translation of requirements between business and technical language can often lead to miscommunication or misunderstanding.

We believe that there are a few vital tools which can be used to enable this cross-domain communication:

  • User stories
  • BDD testing
  • A ubiquitous language
  • A shared vision
  • Situational awareness

In this first blog I will run through how user stories can be used to enable higher-level requirement definition and communication.

What are user stories?

You may be familiar with the standard definition of a user story:

As a , I want to , so that .

For example:

As an administrator, I want to assign user permissions, so that I can control who has access to different parts of the system.

This captures three vital pieces of information:

  • The user
  • The functionality
  • The value of the functionality

However, at endjin we generally prefer to flip this on its head:

In order to , as a , I need to be able to .

This places the value of enabling the feature at the fore-front, meaning that discussion of a feature is always centred around the value that it provides to your users.

It also means that you can group features by those that are similarly beneficial, e.g:

In order to control who has access to different parts of the system, as an administrator, I need to be able to assign user permissions.

In order to control who has access to different parts of the system, as an administrator, I need to be able to remove user permissions.

Why are they useful?

User stories give the business stakeholders a means by which to define the functional requirements, which helps to bridge the communication gap between them and the technical teams. This communication is aided by the definition of clear acceptance / success criteria, which helps the development team to measure whether they are meeting the project outcomes. And, because they also focus on the benefit or value of the functionality, they allow features which don't add value to be quickly deprioritised or removed.

They are also useful for the development team in that they allow work to be split up into manageable work items, which can then be estimated and added to release plans.

User stories are the first step in defining a system. However, a list of user stories doesn't capture any information about the journey that a user might take, or how the story fits into the system as a whole. We need a way of mapping the overall system, in which context we can then place and prioritise our stories.

Story Mapping

At endjin we use a tool called a Story Map to define and record the journeys and shape of the system as a whole.

To construct a Story Map, you take you user stories and organise them into a chronological order which represents users' journey through the system. At this stage these journeys are defined irrespective of the users, and are focused on aiding the illustration of the overall shape. You can then decide what features are vital to the users' journeys (and therefore form part of the MVP - minimum viable product). This allows you keep a record of any scoping decisions, and to view those decisions within the context of the entire system. For example:

Showing the entire Story Map for a career development application. Shows user stories stacked under features, ordered by users' journeys through the system.

If we zoom in to the first few parts of the map:

Showing first few sections of the story map. Features colour coded by users - administrators/managers/members.

We can see that the features are in organised in the logical order:

Find product > Decide to buy > Sign up > Sign in > Set up organisation > Configure organisation > etc...

Each of these headings containing the features and user stories to support them. There is also then a clear line drawn under the features which will be supported as a part of the MVP. And finally, additional colour coding has been added to highlight which type of user the stories apply to.

Using this map, we have built up an overall understanding of the system and how each feature and user story fits into the overall picture. The advantage this has over a normal list (or pile of post-its) containing user stories is that no contextual information is lost.

Overall

I have mentioned the word context a lot in this blog. And I think this is the crucial take-away:

The preservation of the context in which requirements are defined is vital in being able to effectively communicate those requirements to the technical / development team.

Both user stories and story maps are tools which can assist in preserving and communicating that context, and as we will see in my next blog, they can then be used as the building blocks for defining BDD specs. These BDD specs are then the central tool in bridging the communication gap between stakeholders and the technical team, as they provide business-readable, automatable tests for proving out the requirements.

Carmel Eve

Software Engineer I

Carmel Eve

Carmel is a software engineer, LinkedIn Learning instructor and STEM ambassador.

Over the past four years she has been focused on delivering cloud-first solutions to a variety of problems. These have ranged from highly-performant serverless architectures, to web applications, to reporting and insight pipelines and data analytics engines.

In her time at endjin, she has written many blog posts covering a huge range of topics, including deconstructing Rx operators and mental well-being and managing remote working.

Carmel's first LinkedIn Learning course on how to prepare for the Az-204 exam - developing solutions for Microsoft Azure - was released in April 2021. Over the last couple of years she has also spoken at NDC, APISpecs and SQLBits. These talks covered a range of topics, from reactive big-data processing to secure Azure architectures.

She is also passionate about diversity and inclusivity in tech. She is a STEM ambassador in her local community and is taking part in a local mentorship scheme. Through this work she hopes to be a part of positive change in the industry.

Carmel won "Apprentice Engineer of the Year" at the Computing Rising Star Awards 2019.

Carmel worked at endjin from 2016 to 2021.