What’s the problem with software requirements?

In any software project, transforming customer needs into something actionable by the development team is a very challenging task.

Traditional software development processes rely on the concept of requirements for representing inputs to the developers; a software requirement typically dictates what is expected by a software.

An example of software requirement could be:

The menu shall display the name of the user currently logged in

This serves both as an input to a developer and as acceptance criteria for when the feature has been implemented.

The issue of relying exclusively on requirements is that context is usually very little if not missing. Why are we displaying the name of the user in the menu? We don’t know, at least from the requirement: the reason was probably in the head of the requirement author, but it’s now lost.

In short: requirements usually convey what is expected of a software, but not why.

The advent of user stories

Towards the end of the 90s, the need for expressing the features of a software in a way that preserved the why started to be formalized in what are known today as user stories. A user story typically has the form of

As a <role>, I can <capability>, so that <benefit>

Let’s try to rewrite our example requirement:

As a user, I can see my name in the menu, so that I know I’m currently logged in

We can immediately notice two differences:

we had to specify why the name in the menu matters

the name in the menu matters we had to explicitly choose a perspective

Classic requirements used to focus only on the what, rarely describing the context and the intended usage of the feature. That’s one of the reasons why user stories are generally considered to be more effective: adding context helps in avoiding misunderstandings between who writes the requirements and who reads them.

User stories authoring and collaboration

As we saw, user stories are a medium of communication between the product stakeholders (for example, the SCRUM Product Owner) and the developers.

You may wonder, at this point, who is in charge of writing a user story? The developer? The customer? The product owner?

This is a critical point of a process based on user stories, that is often overlooked: user stories risk to end up too vague for a developer to fully understand their context, or too detail-oriented to capture the big picture of the product feature.

In short, there’s an aspect that is paramount for writing a good user story: collaboration. Merely following a user story template is not enough to achieve it.

Collaboration, not grammar, is what drives improvement through user stories

When user stories are not written collaboratively, the so-called lost in translation problem happens. Either missing details will be implicitly filled by developers or the underlying motivation will drown in an ocean of details.

What can you do about it?

So, what can you do to foster collaboration?

Explicitly allocate time for it.

This is a crucial step in the process of writing a user story and most software development methodologies leave it as an “exercise for the reader”. You don’t want to fall into that trap: be explicit about it and require it as a mandatory step whenever you’re sketching a user story.

Here at buildo, we do it in what we call a challenge step: our product owner (the person who represents the customer interests) writes the story. Such story will not be considered ready to go — hence actionable — until challenged by the development team. This spurs dialogue between the developers and the product owner, resulting in many doubts and incomprehensions to be ironed out early in the process.

For example, a challenge step may go like:

PO: “As a user, I can see my name in the menu, so that I know I’m currently logged in”. Team, please challenge this story.

DEV: Is it ok if we show the first name, or do we want the full name?

PO: Good question, I believe first name only is better, because our communication style is informal. Let’s update it: “As a user, I can see my first name in the menu, so that I know I’m currently logged in”

DEV: If the reason is to make the users understand they’re logged in, maybe we should make it more explicit by changing the menu color?

PO: Good point, let’s discuss this with the UX team

and so on, until we reach a point where everybody is aligned with the story and its meaning.

The devil is in the details

So, problem solved, right? No. This challenge step presents us with another issue:

People tend to assume too much about what they understand when it’s time to challenge a user story

As a product owner, you should always factor in the expertise of the development team that will address the story. Let me explain why.

If you are writing a story, which is very vague and contains little detail, the developers may have a lot of questions during the challenge step.

Intuitively, you may think to overcome this issue by adding as many details as possible. However, in our experience, people tend to correlate detail with quality, and this can be risky.

If you fill a story with details, there’s a concrete chance the story won’t be challenged as much as it should, because of a general perception of completeness.

Your job as a story author is to provide enough details so that the essential information won’t be missing, but also avoid giving too many, so that the story will be accurately challenged by the developers to fill in the missing details.

There’s no golden rule, but you can consider two metrics to decide the level of details, based on:

how well the team knows the project: if little, try providing fewer details in order to foster critical thinking

how susceptible the team is to the detail → quality bias (i.e., how likely they will trust the story “brainlessly”, as opposed to challenging it): if the team has a strong bias, try providing even fewer details, to avoid implicit assumptions

An effective technique is to explicitly leave open points and gaps to be filled, to stimulate discussion and encourage a proactive collaboration.

Conclusions