Enough with the User Stories already!
Tags: agile, userstories, bdd, requirements
Published: 2019-04-02 11:07:13

---
title: Enough with the User Stories already!
published: true
description: A Requirements and Specifications Domain Model for agile
tags: agile, userstories, bdd, requirements
---

### The fog of Agile

Agile, at its core, is a set of [guiding principles](https://agilemanifesto.org/principles.html) that are interpreted by the creators and practitioners of various processes, methods and frameworks.  Like a language with many dialects, this results in the same word meaning slightly different things in each dialect. Asking the question "what's a user story?" will give you a dozen different answers. A user story can be a requirement, a feature, a description, an end-goal, a high-level abstraction, a small piece of business value and many other things, depending on who you ask - and *when* you ask them ;) 

I tend to agree with [Mike Cohn's definition](https://www.mountaingoatsoftware.com/agile/user-stories): A user story is a description of a feature. Of course, this only moves the question to "what is a feature?". A quick Googling shows us that definitions abound: a feature is a functionality, a capability, a requirement, a client-valued function expressed in the form <action><result><object>, a part of an Epic, etc. And so it goes on and on.

Here's a common pattern I've come across many, many times and I'm willing to bet that you have too:  A stakeholder asks to look at the 'user stories'. The stakeholder later returns complaining that the user stories are too technical or too abstract or that the wrong actors are involved 

Here's an example:

```
As an end-user 
I want to log-in with my social media credentials
so I don't have to remember extra usernames and passwords
```


That's a user story, right? You can give this to your stakeholder but they'll probably complain that this is too generic to be of any value. And they'll be right.  You then give them this story:


```
As an end-user
When I log-in I want to be re-directed to the login page of my selected Identity Provider
So that, upon entering my credentials, the IP can redirect me back to our system with a valid SAML token
```


The stakeholder looks at you blankly. You don't understand what the problem is. They wanted User Stories, you gave them User Stories, so WTF? The thing is, the stakeholders want something very specific but they don't have the right words to express it because User Stories is a loaded term. Let's hold that thought for a minute.


### A Requirements Domain Model
In his [BDD in Action](https://www.manning.com/books/bdd-in-action) book, John Ferguson Smart elaborates on the usage of Impact Maps, a technique introduced by [Gojko Adzic] (https://www.impactmapping.org/index.html) that is useful for answering the big questions of the Requirements and Specifications model: 

* Why are we building the system?
* Who benefits from it? 
* What do we need to build?
* How will we build it?

These can be directly translated to Requirements and Specifications Domain Entities:

* Business Goal (Why): The intended benefit of our system
* Stakeholder (Who): Someone who is affected by our system
* Capability (What): A system ability that enables the Stakeholders to achieve a business goal
* Feature (How): A functionality that helps deliver a Capability

And, just like that,  we have well-defined Domain Entities. Our requirements are represented by Capabilities in the context of Stakeholders and Business Goals.  Our specifications are the Features, which describe the system functionality we will implement in order to deliver the system's Capabilities. In true BDD fashion, a Feature is described by a User Story followed by a number of scenarios/acceptance criteria. A Feature **is not a User Story**! We can use User Stories to describe Capabilities, Features and Business Goals too.



![Impact Map](https://filedn.com/lBg7bSLnQRakb21qRGSa3pS/Impact%20Map%20social%20login.png)

1. Our system Requirements are the Capabilities in the context of the beneficiary Stakeholders and valid Business Goals
2. We can describe Capabilities and Business Goals with User Stories. This doesn't mean that the stories are these things. 
3. Our Specifications are descriptions of the system behaviour required in order to deliver a Capability, i.e. the Features

###  User Stories are just descriptive devices for Requirements Domain Entities.

So let's jump back to our confused stakeholder. When they asked you for User Stories, what they were asking for was *the Features*! They wanted a description of the system functionality that you'll provide in order to enable them to achieve their goals. Nothing more, nothing less. User Stories are not Domain Entities, they are just descriptors. We need to start communicating using Domain Entities, not descriptors. 

So we provide the following to our stakeholder:


```gherkin
Feature: Login with Twitter
As a end-user with a Twitter account
I want to log-in with my Twitter credentials
so I don't have to know extra usernames and passwords
  
  Scenario: First-time login with Twitter, already signed-on
    Given the user visits our system's login page
    And the user hasn't signed-on our system with Twitter before
    And the user is not already signed onto Twitter
    When the user chooses to sign-on our system with Twitter credentials
    Then the user is presented with a Twitter login page

  Scenario: First-time login with Twitter, not currently signed-on
    Given the user visits our system's login page
    And the user hasn't signed-on our system with Twitter before
    And the user is already signed onto Twitter
    When the user chooses to sign-on our system with Twitter credentials
    Then the user is presented with a Twitter permissions and confirmation page

... (more scenarios)

```

Note how we present a User Story beneath our Feature title in order to best describe and illustrate our Feature. Also note that our Feature would *still be valid and usable even if we didn't use a User Story*. The User Story is not the Feature! It just gives us a nice narrative so it's useful to use it in our Feature. But that is all.  We're not creating User Stories, we're defining Features.   
  
 As Developers, Product Owners or Business Analysts we get flooded with our clients' wishes, needs and desires. Our first question should be: "What should the stakeholders be able to do with our system in order to fulfil their wish or need?". Once we've answered that, our next question should be "How are we going to deliver that capability?". The result of this thought process will give us a set of Specifications (Features) that realise the stakeholders' requirements towards achieving some Business Goals. So let's clear the fog and start talking more about Capabilities and Features, instead of their generic and variant descriptors.  Enough with User Stories already!