The advantages of declarative user stories

The advantages of declarative user stories

BY Simon Schreiber ON MARCH 15, 2022

What exactly is the difference between declarative user stories and imperative user stories and when should you use which? In this post we’ll delve into the advantages and disadvantages for both.

Here is my favorite definition of a User Story:

“User Stories are chunks of desired behavior of a software system. They are widely used in agile software approaches to divide up a large amount of functionality into smaller pieces for planning purposes.”

It comes from Martin Fowler, one of the authors of the Agile Manifesto. He alsowrites:

“Stories are deliberately not fleshed out in detail until they are ready to be developed, you only need enough understanding to allow prioritization with other stories.”

This is exactly the point I would like to pick up on. Over the past few years, working with Product Owners from a wide range of companies and industries, I have observed a pattern in the way User Stories are formulated. Already at the beginning of the product development cycle, Product Owners tend to describe in detail how a software product should behave for the user. They write in an imperative style.

Discover more insights on storytelling for product leaders by Peter Fletcher-Dobson.

The problem with this approach is at this early point in time, neither a product discovery took place nor was there an opportunity to incorporate user feedback into the design process. It also contradicts the idea of agile software development as outlined in the quote above. So instead of anticipating what the user wants with an imperative writing style, it is better to describe in a declarative style what problem should be solved for the user. Let’s delve deeper into imperative user stories.

Imperative user stories

In an imperative User Story, the focus is on the “how”. This can be observed in particular in the Acceptance Criteria. Imperative Acceptance Criteria tend to be very detailed with many steps and they describe how a software product has to behave step by step.

There is a high probability that at the beginning of your career as a Product Owner you will unconsciously formulate requirements in an imperative style. At first glance, this seems to be the obvious approach to write down your thoughts, but it comes with disadvantages. Here is an imperative style example to introduce an “add to cart” button in an e-commerce solution:

(Imperative) User Story

As a user

I want to click on the add to cart button

so that the selected product gets added to my shopping cart.

(Imperative) Acceptance Criteria

1. After the button is clicked, the button label changes from “add to cart” to “added”.

2. Up to the product-specific threshold, each click on the add to cart button results in the product being added to the shopping cart with the selected quantity.

3. If the product is not available, the button is grayed out and not clickable.

4. After clicking on the button, the quantity of products in the header shopping cart icon should be updated asynchronously without reloading the page.

Such a writing style has several disadvantages:

• The Product Owner anticipates conceptual decisions for a UX Designer.
• The Product Owner anticipates design decisions for a UI Designer.
• The Product Owner anticipates technical decisions for a Software Engineer.
• The Product Owner describes in detail how the “add to cart” has to behave, but forgets to describe which value the feature should provide from a user perspective.
• If the team comes up with a better solution during the Sprint, the Acceptance Criteria must be updated retrospectively.

Nevertheless, there are also valid areas of application for an imperative writing style. For example, if a Technical Product Owner wants to make a routine change to an API that is already in production, it is not necessary to describe an already known user value again. It is more efficient to write down the technical change to be made in detail as an imperative User Story in the Product Backlog.

Read: API’s in your product – the good, the bad, the ugly

Declarative user stories

While an imperative User Story describes in detail how the software product has to behave, a declarative writing style is more about the “what”. The approach is to describe what value is created for the user.

Read: The World is Colorful, so why Shouldn’t our Users be? by Mirja Bester

In comparison to the imperative User Story example before, a declarative formulation of the same “add to cart button” with a stronger focus on user value could be as follows:

(Declarative) User Story

As a user

I want to collect products while I browse

so that I can order them all in one go.

(Declarative) Acceptance Criteria

1. The user can see whether the product is already in the shopping cart.

2. The product can be added to the shopping cart until the product-specific threshold is reached.

3. The user can see if the product is in stock.

4. The current number of products in the cart should be visible at all times.

The declarative writing style has the following advantages:

• By focusing on the problem to be solved, the Product Owner promotes a collaborative work environment between Software Engineers, business stakeholders and UX Designers.
• There is a high probability that this cross-functional group will produce a better result for the user than the product owner alone.
• Due to the lower level of detail, a lower frequency of changes can be observed in declarative User Stories.

But there are also possible drawbacks to consider in a declarative writing style. If the Product Owner does not formulate in detail how the solution should look like, he must ensure to collaborate closely with the development team, UX and stakeholders during the Sprint. The Product Owner cannot expect a good result if he throws declarative User Stories over the fence, is difficult to reach during the Sprint and shows up again in the Sprint Review.

The takeaway

As a Product Owner, how do you decide whether an imperative or a declarative writing style is more suitable? You should consider the following two points when making your decision:

• On the one hand, the current phase of the product life cycle is important. A declarative style unfolds its strengths particularly in an innovative environment with a high degree of uncertainty. If there is still no clarity about the product-market-fit or if no usability tests have been carried out with the user interface to be developed, it makes no sense to get lost in the details. The Product Owner should focus on the “what” rather than the “how”.
• On the other hand, the type of the change and the context are important. Especially when it comes to recurring and routine tasks with a high planning certainty, nothing is wrong with an imperative approach.

If a Product Owner now decides to change the writing style, this should be aligned with the development team and the Scrum Master. After the change, it is also advisable to wait a few iterations and find out in a Sprint Retrospective how the new writing style affected the collaboration within the team and the stakeholders involved.

Discover more insights on user stories.