Ben Degens
Intro
Since I took the Architects Master Class at IDesign, I’m thinking more and more about how to capture requirements properly and of course: how not to do it. In this particular blog I’m looking into the user story format. A lot of customers that are (going) into scrum/agile, choose this format to describe their wished features or functionalities. How are they often used and what are the pitfalls?
What is a user story?
User stories are simple, yet extremely powerful constructs: they describe pieces of functionality from a user’s point of view, expressed in a solid, compact way. They reflect what a particular class of user needs and the value to be gained.
User stories help to achieve cross-team clarity on what to build, for whom, why, and when. Since they are easy to define, understand, and revise, they can become the standard way to communicate and summarize the functionality of the product by both technical and non-technical members.
George Krasadakis - How (and why) to write great User Stories
The format looks something like the following:
”As a [role or persona], I want [to have something], so that [I get some value/benefit]”
As it could be great to do some first analysis of what is needed to be build or to use as a template for the business to deliver their wishes in, there are dangers in (mis)using them further in the development cycle.
How are they often used?
At most customers it basically comes down to this: a user story becomes a work item for a development team to implement.
There are customers, and I’m not even kidding, that will send a one liner userstory directly to the dev team without working it out properly. Of course everything in between ‘working out nothing’ and ‘capturing everything’ is possible. Adding some form of description, a screenshot, a workflow, a detailed design, and so on. Depending on how well the customer structured it’s development methodology, the item will be more detailed before it goes to the people building it.
Tip of the iceberg
Userstories not worked out properly and going directly to the team is a problem. You still need specs and a further breakdown of the actual requirements. A great example of this is the user story of Google Search. It probably looks something like:
“As a Google User I want to have the best search results, so that I have correct and up to date information”
Two buttons and a textbox, how hard can it be. This is literally the tip of the iceberg looking at the monster system that is behind all of this. Of course its exaggerated to make a point, but I’ve seen my share of userstories in the jungle of (sprint)backlogs looking like this.
Handling specs
What is the type of project?
Is there already an architecture and is the team maintaining a system? Or are we building an entirely new system or maybe even a system of systems. There is obviously a different approach in how to handle each kind of project. Compare it to building or maintaining a skyscraper.
Maintaining a skyscraper could be done by a maintenance team. Replace a lamp, renovate the staircase, replace toilet or something bigger: renovate an entire floor. Depending on how well the maintenance team is organized they could do most of these things without help of an architect. When renovating an entire floor it get’s a little more interesting as there are probably more requirements etc.
When there is a new skyscraper to be build, we cannot just hire a contractor and throw requirements (or user stories) to his team to implement. The specs need to be clear including the design and construction calculations.
What is a requirement or a feature?
Let’s talk about what a requirement or a feature actually is. Depending on what you’re making and what the context is, a feature in software architecture ‘does not really exist’.
I could have a functionality to place an image somewhere or replace a button color by another, but I’m not talking about those small requirements. Those can easily be described in a user story as a change or added to a UX design or whatever. A great example from the book Righting Software is:
”As a car user I want to drive from A to B, so I can be there faster then by foot and save time”
Great! Let’s build this requirement into the car, but what actual component within the car represents driving from A to B? Not one, right? It’s the integration of components that makes this possible. This tells you that a feature is always some kind of interaction between components. In software engineering we call this a use case. Why not document this interaction, wouldn’t it be clearer for everyone on what is needed to be builded, tested and deployed?
Use cases
You could write a blog post or a book about how to discover and document use cases. To stay in scope of this article, let’s discuss how to capture requirements as behavior. As discussed, one liner user stories are open for interpretation where an interaction (between components) is more detailed and less open for discussion. One of the best ways to do this is using an activity diagram:
Advantages
Making it visual is easy for humans to understand, much better than writing it out in text. Humans are made for processing images, we are visualizing a lot longer than we’re reading.
Makes it less open for interpretation than describing the feature in a few sentences.
Easy to talk about and should be understandable for both a developer and a business person
As an architect you can use the use cases as input for creating your design
Disadvantages
More work to create diagrams (rule of thumb: if there is a nested if, use a diagram, otherwise write it out)
The example is a functional use case, there is no interaction between components visible, that is part of the technical specs. From this functional diagram an architect could go and find out what components are needed to support the set of (core) use cases.
Other pitfalls
Functional stories going to the team directly without analysis or architecture input
Double, tripple, etc. requirements will be there. Customer A uses another vocabulary as customer B, both stories will be put on the backlog when it’s actually the same.
A functional work breakdown will result in developers touching the same components multiple times (and testing and deploying, expensive).
Calling everything a user story and using the format everywhere
User stories explaining the “how” and not the “why”. People that should provide requirements are now giving you solutions hiding as requirements. Although, this happens all the time, also when not using user stories.
Perspective and context
Everything comes down to context and the people working in it. How experienced are they, what are their skills and what are they working on (as discussed, a brand new project is different from maintaining a product etc.). At some customers the user story format works better than others. There could be a single application to maintain and product owner who has been there for years and knows his way around or there could be a team that (tries to) maintains 20 different applications with a new product owner that doesn’t ‘own’ a single product (yet). I’ve seen both.
Wrap it up
For me it’s clear: user stories will be misused. Think about the type of project you’re working on and how the process of structuring requirements is done. Do not use them like described in the “how are they often used” section, it’s a horrible way of capturing requirements and will be a pain in the ass when not worked out properly. Try to capture requirements as behavior and make them visual 👀.
