DEV Community

Engineering guide to writing correct User Stories

Nikita Sobolev on March 26, 2019

Originally published in my blog: https://sobolevn.me/2019/02/engineering-guide-to-user-stories Agile people are obsessed with writing user stories...

Read full post

Bence Szabo • Mar 27 '19

Very good article! 🎉

I wonder how you manage really complex situations? Let me try to describe it with a dumb example. Imagine you're writing specs for an app similar to instagram (and with really fine-grained control), and you end up writing a scenario like:

  Scenario: get notified of a new reaction
    Given I posted a picture on my account
    And people are allowed to react on the picture
    And notifications for reactions is turned on
    ...
    And someone liked the picture
    When I login
    Then a popup is shown that someone reacted to my picture

I remember working with scenarios that had like 10 Given statements or so. And I couldn't really see how the number of statements could have been reduced.

Nikita Sobolev • Mar 28 '19 • Edited

You have to apply abstraction to merge several steps together. Or apply decomposition to separate them. Let me explain, please.

For example: you want to be notified when someone posts likes on your posts/images/etc. We all know and love this feeling. For this situation it does not really matter how did you create this content. You only write specs for the reaction part.

Feature: authors are notified about readers' reactions

Scenario: get notified of a new reaction
   When a reader reacts on author's content
   Then author gets a notification about it

Scenario: do not get notified about new reactions when notifications are disabled
   When author's notifications for reactions are disabled 
   And a reader reacts on author's content
   Then author gets no notification about it

This is a first feature: receiving notifications. Disabling the ability to react is a different feature. And should be specified as a different feature. Because notifications only make sense when readers are allowed to posts reactions. However, you can mention that all content for feature authors are notified about readers' reactions is allowed to be reacted on. You can use Background tag for that: relishapp.com/cucumber/cucumber/do...

I hope this helps you.

Bence Szabo • Mar 28 '19

Thanks for the reply!

Then this implies to me that I might end up writing long Backgrounds.

Do you maybe know some mature open source projects where they're doing BDD the right way? I would love to analyze something in depth.

Nikita Sobolev • Mar 28 '19

Nope, sorry :sad:

Jon Lauridsen • Dec 25 '19

I only know the theory, but I think the scenario setup can be abstracted in the direction you talk about it in the office. That is, do you go around saying “let’s make a great notification feature for posts with notifications enabled and permissions are allowed and the user clicks etc etc”? No, you have some shorthand that the organisation accepts (or is ready to adopt). Internal language can have deep meaningful abstractions and that worth capitalising on. The BDD part of Gurkins is to identify those ways of talking.

Well, I think so at any rate. I think your question is really good and gets to the heart of the complexities with full behavioural test coverage.

Christian Schulze • Mar 28 '19

Great article!

Hypothetical situation, how would you write a new story in a subsequent sprint if you wanted to add push notifications to the existing feature?

Nikita Sobolev • Mar 28 '19

Well, you can copy-paste existing scenarios/features. And edit them to match your new feature.
Or, you can use Scenario Outline tag to parametrise your specs. You can use it if features are absolutely similar.

Christian Schulze • Mar 28 '19

Thanks for the response Nikita, however I don't think I was clear enough with my question.

Ignoring any acceptance tests, dealing with just the story:

Tracking issues progress
As an architect
I want to have up-to-date information about Gitlab issues
So that I can overview and track the issues' progress

So this was for using webhooks, but coming back for a second sprint to add push notifications I'm unsure how the new story would be written, since it doesn't contain any implementation details to differentiate from the original story. What do you think?

Nikita Sobolev • Mar 28 '19 • Edited

That's the most important part: your user story does not change. And it should not be duplicated as well.

You can write new Scenarios in the same file. You can even use parametrisation to inject dependencies to some of your existing Scenarios. And cover new corner-cases inside new Scenario blocks.

Example:

Feature: Tracking issues progress
  As an architect
  I want to have up-to-date information about Gitlab issues
  So that I can overview and track the issues' progress

  Scenario Outline: new valid <payload> is received
    Given <payload> is valid
    And <payload> is authenticated
    When it is received
    Then a new issue is created

  Examples:
    |payload|
    |issue webhook|
    |push notification|

Christian Schulze • Mar 28 '19

Right got it, thanks for clarifying 👍

Van Ly • Apr 2 '19

Once a user story is done, it should not be back to backlog. If you have some enhancement, create new story.

You can write like this:

As an architect, I want to receive notifications on my mobile when there is any update from Gitlab

Van Ly • Apr 3 '19

Ah, I might misread your scenario. In case that you mentioned about the push notification between GitLab and your system (in additional to webhook), you may create a technical task to address the issue.

rgalen.com/agile-training-news/201...

In the end, technical task should only be considered if it has some business value in it. Try to find some way to describe the value, otherwise, if you want to go fast and the product owner and stackholders understand the value behind the lines, then just use technical task.

Carl • Mar 26 '19

This is amazing! The fine-tuning of a very common issue is an awesome example. Showing this to my work colleagues, and I'm going to try and use this technique going forward with whatever work I do. I always find that putting in a little extra effort upfront does wonders for the quality and speed of producing an outcome.

Thanks for the write-up!

P.S. compliment -> complement

Nikita Sobolev • Mar 27 '19

Thanks!

P.S. Fixed.

Allison Walker • Apr 2 '19

Great tips. I'm plan to share this with my network.

I wonder if the user story could be improved even more, by splitting on the 'and'? For instance, "So that I can overview and track the issues' progress" becomes, "So that I can overview issues..." and "So that I can track issues"? Maybe I'm not familiar with the term "overview"?

Maxime Moreau • May 9 '19

Oh boy! That's a really interesting method, I'll give it a try for sure.
I'm having this trouble, a simple user story that's hard to implement so the estimation is bad and I didn't know how to solve this effectively, I think this method could do the job!

Thanks a ton.