DEV Community

Cover image for Engineering guide to writing correct User Stories

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...
Collapse
 
finnhvman profile image
Bence Szabo

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.

Collapse
 
sobolevn profile image
Nikita Sobolev • 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.

Collapse
 
finnhvman profile image
Bence Szabo

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.

Thread Thread
 
sobolevn profile image
Nikita Sobolev

Nope, sorry :sad:

Collapse
 
jonlauridsen profile image
Jon Lauridsen

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.

Collapse
 
christianschulze profile image
Christian Schulze

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?

Collapse
 
sobolevn profile image
Nikita Sobolev

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.

Collapse
 
christianschulze profile image
Christian Schulze

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?

Thread Thread
 
sobolevn profile image
Nikita Sobolev • 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|
Thread Thread
 
christianschulze profile image
Christian Schulze

Right got it, thanks for clarifying 👍

Thread Thread
 
ltvan profile image
Van Ly

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

Thread Thread
 
ltvan profile image
Van Ly

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.

Collapse
 
carlfoster profile image
Carl

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

Collapse
 
sobolevn profile image
Nikita Sobolev

Thanks!

P.S. Fixed.

Collapse
 
allison profile image
Allison Walker

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"?

Collapse
 
mx profile image
Maxime Moreau

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.

Collapse
 
hdennen profile image
Harry Dennen

THIS GUY GETS IT.
THIS GUY GETS IT

Collapse
 
mgh87 profile image
Martin Huter

Thanks for the share, and this nice approach how to link your stories better to your source! ❤️

Collapse
 
conw_y profile image
Jonathan

Bloody awesome! I hope many developers (and BA's) read this. Clear thinking and clear user stories leads to clear and usable software.