Engineering guide to writing correct User Stories

<strong>Originally published in my blog</strong>:&nbsp;<a href="https://sobolevn.me/2019/02/engineering-guide-to-user-stories" target="_blank">https://sobolevn.me/2019/02/engineering-guide-to-user-stories</a>

Agile people are obsessed with writing user stories. And it is a powerful instrument indeed. But, from my practice a lot of people are doing it wrong.

Let's see an example:

As a user
I want to receive issue webhooks from Gitlab
So that I can list all current tasks

Seems like a valid user story, doesn't it? In fact, this tiny story contains multiple issues. And if you cannot find at least 8 mistakes in it - this article will be worth reading for you.

This article is split into three main parts:

  1. Getting better with the default user story format
  2. Rewriting user stories with BDD to make them verifiable
  3. Linking user stories with tests, source code, and documentation

While some parts might look more interesting to different categories of readers, it is important for everyone to understand the full approach.

Spotting and fixing problems

As we all know all our requirements must be correct, unambiguous, complete, consistent, ranked, verifiable, modifiable, and traceable even if they do not look like requirements at the first glance.

User stories tend not to have some of the given characteristics. We need to fix that.

Using consistent language

Is "receive issue webhooks" and "list all current tasks" somehow connected?

Are "tasks" and "issues" the same thing or not? It might be completely different things or just bad wording. How do we know?

That's what glossaries are for! Every project should start with defining specific terms that will build ubiquitous language for the future. How do we build this glossary in the first place? We ask domain experts. When we encounter a new term: we make sure that all domain experts understand this term correctly and similarly. We should also take care that the same term might be understood differently in different situations and contexts.

Let's say that in our case after consulting a domain expert we have found out that "task" is the same thing as "issue". We now need to remove the incorrect term.

As a user
I want to receive issue webhooks from Gitlab
So that I can list all current tasks

Excellent. Using the same words for the same entities is going to make our requirements more clear and consistent.

Users do not want your stuff

When we have modified the last line it caught my attention that a goal of the user is to "list all current issues". Why does this poor user want to list some issues? What is the point in doing it? No users want that. This requirement is simply incorrect.

This is an indicator of a very important problem in writing requirements. We tend to mix our and user's goals. And while our goal is to please our users, we should concentrate on them in the first place. Making their needs value more than ours. And we should explicitly express that in our requirements.

How do we know what the user wants? Again, we don't. We need to consult real users or their representatives about it. Or make a hypothesis yourself if we cannot ask anyone.

As a user
I want to receive issue webhooks from Gitlab
So that I can list all current tasks

After collecting more feedback we know, that our users need to know the progress of a project. Not listing issues. That's why we need to receive and store information about issues from the third-party service.

Removing technical details

Have you ever met a single person who literally wants to "receive issue webhooks"?

No one wants to do that. In this case, we also mix two different concerns together.

There's a clear separation between user's goals and technical ways to achieve them. And "to receive issue webhooks" is clearly an implementation detail. Tomorrow it can be changed to WebSockets, push notifications, etc. And the user's goal will not change because of that.

As a user
I want to receive issue webhooks from Gitlab
So that I can list all current tasks

See? Only important information is left, implementation details are stripped away.

Clarifying roles

Just by the context, it is pretty clear that we are dealing with some kind of developer-related tool. We use Gitlab and issue management. So, it would be not hard to guess that we will have different kinds of users: juniors, middle devs, and seniors. Maybe project managers and other people as well.

So, we come to the roles definitions. All projects have different types of users. Even if you think that are no explicit types. These roles can form depending on the way or goal of why your product is used. And these roles must be defined the same way we define terms for the project.

What kind of users are we talking about in this particular user story? Will junior devs overview and track the progress the same way as project managers and architects? Obviously, not.

As a user
I want to receive issue webhooks from Gitlab
So that I can list all current tasks

After making an intelligent guess we can separate different user stories by different user roles. And it gives us fine-grained control over the features we ship and whom we ship these features too.

Extending user stories

This simple As a <role or persona>, I want <goal/need> so that <why> is great, since it is succinct and powerful at the same time. It gives us a perfect way to communicate. However, there are several disadvantages of the following format we should - at least - know about.

Making user stories verifiable

The problem with given user story that we still have is that it is not verifiable.

How can we be sure that this story (now or still) works for our users? We cannot.

There is no clear mapping between this user story and our tests. It would be awesome if one can write user stories as tests...

Wait, but it is possible! That's why we have Behavior-driven developmentand As a <role or persona>, I want <goal/need> so that <why> language. That's why BDD was created in the first place. It means that we can rewrite our user story in the As a <role or persona>, I want <goal/need> so that <why> format to make it verifiable.

As a user
I want to receive issue webhooks from Gitlab
So that I can list all current tasks

Now, this user story is verifiable. We can literally use it as a test and track its status. Moreover, we now have a mapping between our higher-order requirement and an implementation detail which will allow us to understand how exactly we are going to fulfill this requirement. Notice, we do not replace the business requirement with implementation details, but we complement it.

Spotting the incompleteness

Once we used As a <role or persona>, I want <goal/need> so that <why> to write our user stories we started to write scenarios for our user stories. And we found out that there might be several scenarios for the same user story.

Let's take a look at the first scenario we made: "new valid issue webhook is received". Wait, but what will happen when we receive an invalid webhook? Should we still save this issue or not? Maybe we will need to do some extra work as well?

Let's consult Gitlab's documentation as a source of the information what can go wrong and what to do in these cases.

Turns out we have two different invalid cases that we need to handle differently.

First one: Gitlab accidentally sends us some garbage. Second one: our authentication tokens do not match.

Now we can add two more scenarios to make this user story complete.

As a user
I want to receive issue webhooks from Gitlab
So that I can list all current tasks

I like how this simple user story now feels like a quite complex one. Because it reveals its internal complexity to us. And we can adjust our development process to the growing complexity.

Ranking user stories

Currently, it is not clear how important it is for architects to "overview and track issues' progress". Is it more important than other user stories we have? Since it looks rather complex maybe we can do something easier and more important instead?

Ranking and prioritization are crucial to any product and we cannot ignore it. Even if we have user stories as the only way to write requirements. There are different methods to prioritize your requirements, but we recommend to stick to MoSCoW method. This simple method is based on four main categories: As a <role or persona>, I want <goal/need> so that <why>, As a <role or persona>, I want <goal/need> so that <why>, As a <role or persona>, I want <goal/need> so that <why>, and As a <role or persona>, I want <goal/need> so that <why>. And implies that we will have a separate prioritized table of all user stories in a project somewhere in the documentation.

And again, we need to ask users about how important each feature is.

After several conversations with different architects that work with our product we have found out that this is an absolute As a <role or persona>, I want <goal/need> so that <why>:

FeaturePriorityAuthenticated users must be able to send private messagesMustArchitects must track issues' progressMustThere should be a notification about incoming private messageShouldMultiple message providers could be supportedCouldEncrypted private messages won't be supportedWon't

So, we can now modify the user story's name to map it to the prioritized feature:

As a user
I want to receive issue webhooks from Gitlab
So that I can list all current tasks

We can even link them together. Just use hyperlinks from your ranked requirements table to the feature file with the user story.

This way we can be sure that this feature will be one of the first one to be developed since it has the highest priority.

Linking everything together

Without proper care, you will soon end with a mess of user stories, tests, source code, and documentation. With the constant growth of your project, it will be impossible to tell which parts of the application are responsible for what business use-cases. To overcome this problem we have to link everything together: requirements, source code, tests, and docs. Our goal is to end up with something like this:

I will use As a <role or persona>, I want <goal/need> so that <why> to illustrate the principle.

I can define use-cases as a set of unique high-level actions your app can perform (it looks pretty similar to Clean Architecture's point of view).

I usually define a package called As a <role or persona>, I want <goal/need> so that <why> and put everything inside so it would be easy to overlook all existing use-cases at once. Each file contains a simple class (or a function) that looks like so:

As a user
I want to receive issue webhooks from Gitlab
So that I can list all current tasks

I use As a <role or persona>, I want <goal/need> so that <why> and As a <role or persona>, I want <goal/need> so that <why> directive to include the same file we use for tests to document the domain logic. I also use the glossary to indicate that As a <role or persona>, I want <goal/need> so that <why> is not just a random word: it is a specific term that we use in this project.

This way our tests, code, and docs will be as coupled as possible.

And we will need to worry less about them. We can even automate this process and check that all classes inside As a <role or persona>, I want <goal/need> so that <why> have As a <role or persona>, I want <goal/need> so that <why>directive in their docs.

You can also use this class to test our user story. This way you will bind requirements, tests, and the actual domain logic implementing this user story.

Job done!

Conclusion

This guide will help you to write better user stories, focus on their needs, keeping your source code clean, and reusing as much as we can for different (but similar) purposes.


Thanks for reading :heart: If you liked this post, share it with all of your programming buddies! Follow me on Facebook | Twitter

Learn More

Machine Learning with Python, Jupyter, KSQL and TensorFlow

Introduction to Python Microservices with Nameko

Comparing Python and SQL for Building Data Pipelines

Python Tutorial - Complete Programming Tutorial for Beginners (2019)

Python and HDFS for Machine Learning

Build a chat widget with Python and JavaScript

Complete Python Bootcamp: Go from zero to hero in Python 3

Complete Python Masterclass

Learn Python by Building a Blockchain & Cryptocurrency

Python and Django Full Stack Web Developer Bootcamp

The Python Bible™ | Everything You Need to Program in Python

Learning Python for Data Analysis and Visualization

Python for Financial Analysis and Algorithmic Trading

The Modern Python 3 Bootcamp

Mobile App Development Company India | Ecommerce Web Development Company India

Mobile App Development Company India | Ecommerce Web Development Company India

Best Mobile App Development Company India, WebClues Global is one of the leading web and mobile app development company. Our team offers complete IT solutions including Cross-Platform App Development, CMS & E-Commerce, and UI/UX Design.

We are custom eCommerce Development Company working with all types of industry verticals and providing them end-to-end solutions for their eCommerce store development.

Know more about Top E-Commerce Web Development Company

Python Tutorial - Learn Python for Machine Learning and Web Development

Python Tutorial - Learn Python for Machine Learning and Web Development

Python tutorial for beginners - Learn Python for Machine Learning and Web Development. Can Python be used for machine learning? Python is widely considered as the preferred language for teaching and learning ML (Machine Learning). Can I use Python for web development? Python can be used to build server-side web applications. Why Python is suitable for machine learning? How Python is used in AI? What language is best for machine learning?

Python tutorial for beginners - Learn Python for Machine Learning and Web Development

TABLE OF CONTENT

  • 00:00:00 Introduction
  • 00:01:49 Installing Python 3
  • 00:06:10 Your First Python Program
  • 00:08:11 How Python Code Gets Executed
  • 00:11:24 How Long It Takes To Learn Python
  • 00:13:03 Variables
  • 00:18:21 Receiving Input
  • 00:22:16 Python Cheat Sheet
  • 00:22:46 Type Conversion
  • 00:29:31 Strings
  • 00:37:36 Formatted Strings
  • 00:40:50 String Methods
  • 00:48:33 Arithmetic Operations
  • 00:51:33 Operator Precedence
  • 00:55:04 Math Functions
  • 00:58:17 If Statements
  • 01:06:32 Logical Operators
  • 01:11:25 Comparison Operators
  • 01:16:17 Weight Converter Program
  • 01:20:43 While Loops
  • 01:24:07 Building a Guessing Game
  • 01:30:51 Building the Car Game
  • 01:41:48 For Loops
  • 01:47:46 Nested Loops
  • 01:55:50 Lists
  • 02:01:45 2D Lists
  • 02:05:11 My Complete Python Course
  • 02:06:00 List Methods
  • 02:13:25 Tuples
  • 02:15:34 Unpacking
  • 02:18:21 Dictionaries
  • 02:26:21 Emoji Converter
  • 02:30:31 Functions
  • 02:35:21 Parameters
  • 02:39:24 Keyword Arguments
  • 02:44:45 Return Statement
  • 02:48:55 Creating a Reusable Function
  • 02:53:42 Exceptions
  • 02:59:14 Comments
  • 03:01:46 Classes
  • 03:07:46 Constructors
  • 03:14:41 Inheritance
  • 03:19:33 Modules
  • 03:30:12 Packages
  • 03:36:22 Generating Random Values
  • 03:44:37 Working with Directories
  • 03:50:47 Pypi and Pip
  • 03:55:34 Project 1: Automation with Python
  • 04:10:22 Project 2: Machine Learning with Python
  • 04:58:37 Project 3: Building a Website with Django

Thanks for reading

If you liked this post, share it with all of your programming buddies!

Follow us on Facebook | Twitter

Further reading

Complete Python Bootcamp: Go from zero to hero in Python 3

Machine Learning A-Z™: Hands-On Python & R In Data Science

Python and Django Full Stack Web Developer Bootcamp

Complete Python Masterclass

Python Programming Tutorial | Full Python Course for Beginners 2019 👍

Top 10 Python Frameworks for Web Development In 2019

Python for Financial Analysis and Algorithmic Trading

Building A Concurrent Web Scraper With Python and Selenium

Hire PHP Developer and Web Developer for your Online Business

Hire PHP Developer and Web Developer for your Online Business

PHP is widely used open-source scripting language it helps in making dynamically easy your websites and web application. Mobiweb Technology is your best technical partner and offering you solution for any kind of website and application...

PHP is widely used open-source scripting language it helps in making dynamically easy your websites and web application. Mobiweb Technology is your best technical partner and offering you solution for any kind of website and application development. To hire PHP developer and web developer at affordable prices contact Mobiweb Technology via [email protected]