If you ask many developers what a “user story” is, you will be told that it is a software requirement expressed using a prescribed formula:
As a category of person, I want to do a thing so that some goal is attained.
This is very close to the formula of a Hoare Triple that is used to make assertions about the ways in which computer programs work: Given that I am this category of person, when the software lets me do this thing, then I will attain a certain goal. It is perhaps no surprise that software engineers use the same pattern for requirements and for tests.
But this is not the whole truth about the user story. Before we go into what is missing, let us take a moment to understand why this partial story is so popular. Many software engineers do not engage with the broad “software engineering literature” very much: through the act of reading this magazine you are placing yourself at the pinnacle of software engineering curiosity!
So most people who know what a user story is were told what a user story is. But we still need an on-ramp for our partial explanation: we need to know why people think it is that sentence above and no more. A great book on the topic is User Stories Applied by Mike Cohn. If you are not sure about this whole user stories thing, you may not want to commit to buying the book, but that is OK, you can sign up and download a sample chapter from Mountain Goat Software.
That chapter happens to be the one that describes the one-sentence formulation above. So here is my theory. Some people heard that the Agile folks were using this “user story” thing that is way easier than use cases. Curious, they read the sample chapter from Cohn’s book, which told them about this one-sentence formulation. They decided to try it out. “What is that?” “It is a user story. It is an easy way to capture requirements. I learned about it from the book, User Stories Applied by Mike Cohn.”
On with the show: my point is that there is a lot more to capture about software requirements than the headline, if you want to make good software that satisfies your customers. This is the stuff that goes on the back of the index card: the stuff you find out when you discuss the title with anyone.
I say “index card” because that is how this whole agile thing was designed. It was at a time when a lot of processes, including those in software companies, had not been computerised: indeed it was in many ways a protest against the automation we saw in Computer-Aided Software Engineering (CASE) tools. Agile software development is done in one room, with lots of talking, and high-visibility, highly-mutable information captures: walls full of post-it notes and index cards.
It is important to acknowledge the dual nature of back of the index card information. It is of conversations, but it should not be confined to conversation. It is part of the formal documentation of the project, but will not be uncovered if restricted to formal requirements-gathering ceremony. It exists in the liminal space between conversation and meeting, between process and chaos, between the TPS report and the back of the cigarette packet.
I have previously written about the requirements trifecta: companies do well when their products balance the company’s visionary direction; market expectation; and technical reality. So the back of the index card tracks all of that information. Is this story linked to any others in ways that are important for the vision to make sense? Are there any particular customers or leads who would benefit from the value realised by this story, and what effect does knowing that have on priorities? Is there technical work that needs to be done to realise this story, and how does that affect delivery estimates?
And then there is all the additional detail that did not fit in the one-sentence description on the front of the card. For example, Atlassian give this example of a user story:
As Max, I want to invite my friends, so we can enjoy this service together.
I have questions! Some of them:
- Who is Max?
- Why do we care what Max wants?
- Does Max want to choose which friends they invite?
- How many friends does Max have?
- Over what timespan will these invitations get sent?
- Over what medium will these invitations get sent?
- What will Max’s friends experience when they receive the invitation?
- How will Max’s friends interact to accept or decline the invitation?
- What is the “together” nature of this service?
- What is this service?
- What operational costs can we accept in deploying this invitation capability?
- Are there any privacy, security, or regulatory implications to consider when building this invitation feature?
- How will invitations fit into the existing code?
- Can Max retract an invitation?
- What happens in Max leaves the service before one of their invitations is accepted?
- Does Max represent a broader population of users?
Any answers to those and similar questions that do not get written down somewhere the whole team can see and discuss will become assumptions. Did we all make the same assumptions? Do you feel lucky? Do ya?
Cover photo by Kate Trysh on Unsplash.
