Engineering guide to writing correct User Stories

<strong>Originally published in my blog</strong>:&nbsp;<a href="" target="_blank"></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!


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 for Beginners (2019) - Learn Python for Machine Learning and Web Development

Python Tutorial for Beginners (2019) - Learn Python for Machine Learning and Web Development


00:00:00 Introduction

00:01:49 Installing Python

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

Top 10 Python Frameworks for Web Development In 2019

Top 10 Python Frameworks for Web Development In 2019

In this article, we are going to share our list of the top 10 Python frameworks for web development which we believe will help you to develop awesome applications and your technical abilities.

In this article, we are going to share our list of the top 10 Python frameworks for web development which we believe will help you to develop awesome applications and your technical abilities.

Given how dynamic web development has become, the popularity of Python frameworks seems to be only increasing. This object-oriented, powerfully composed, interpreted, and interactive programming language is easy to **learn **and effectively lessens the development time with its easy-to-read syntax and simple compilation feature. That’s reason enough why it is continuously gaining popularity.

Also, it has a vast number of Python libraries that support data analysis, visualization, and manipulation. Consequently, it has advanced as the most favored programming language and is now considered the “Next Big Thing” for professionals.

Since **Python **does not accompany the built-in features required to accelerate custom web application development, many developers choose Python’s robust collection of frameworks to deal with the subtleties of execution.

**Python **gives a wide scope of frameworks to developers. There are two types of Python frameworks – **Full Stack Framework **and Non-Full Stack Framework. The full-stack frameworks give full support to Python developers including basic components like form generators, form validation, and template layouts.

There is a cluster of full stack options when we talk of Python frameworks. Listed below are the top 10 full-stack web frameworks for **Python **that you should be using in 2019 valuable for enhancing your technical abilities.


Django is a free and open-source Python framework that enables developers to develop complex code and applications effectively and quickly. This high-level framework streamlines web application development by giving different vigorous features. It has a colossal assortment of libraries and underscores effectiveness, less need for coding, and reusability of components.

A few of the key features of Django, such as authentication mechanism, URL routing, template engine, and database schema migration implements ORM (Object Relational Mapper) for mapping its objects to database tables. The framework underpins numerous **databases **including PostgreSQL, MySQL, Oracle, and SQLite, which implies that a similar coding works with various databases.

Django’s cutting-edge features help developers in achieving basic web development tasks like user authentication, RSS feeds, content services, and sitemap. Due to its incredible features, Django framework is extensively used in several high-traffic sites, which include Pinterest, Instagram, Bitbucket, Mozilla, Disqus, and The Washington Times.


**CherryPy **is an open source Python web development framework that implants its very own multi-strung server. It can keep running on any working framework that supports Python. **CherryPy **features incorporate thread-pooled web server, setup framework, and module framework.

A moderate web framework enables you to utilize any sort of technology for data access, templating, etc. Yet, it can do everything that a web framework can, for instance, handling sessions, static, file uploads, cookies, and so on.

Regardless of the accessible features and advantages like running on multiple platforms, built-in support for profiling, reporting, and testing, some developers may imagine that there is a requirement for easy and enhanced documentation. It doesn’t constrain you to use a specific template engine, ORM, so that you can use anything you wish to use.


**Pyramid **is a Python framework that underpins validation and directing. It is incredible for growing huge web applications, as CMSs, and it is valuable for prototyping an idea and for developers chipping away at API projects. Pyramid is adaptable and can be utilized for both easy as well as difficult projects.

Pyramid is enhanced with features without driving a specific method for completing things, lightweight without abandoning you all alone as your app develops. It is a most valued web framework among experienced Python developers by virtue of its transparency and measured quality. It has been used by a moderate team and tech giants like Mozilla, Yelp, Dropbox, and SurveyMonkey.

The pyramid is reliably known for its security arrangements, which makes it easy to set up and check access control records. Another inventive functionality worth uncovering is Pyramid’s Traversal framework for mapping URLs to code, which makes it simple to develop RESTful APIs.


**TurboGears **is an open-source, free, and data-driven full-stack web application Python framework. It is designed to overcome the inadequacies of various extensively used web development frameworks. It empowers software engineers to begin developing web applications with an insignificant setup.

**TurboGears **enables web developers to streamline web application development utilizing diverse JavaScript development tools. You can develop web applications with the help of elements such as SQLAlchemy, Repoze, WebOb, and Genshi, much faster than other existing frameworks. It supports different **databases **and web servers like Pylons.

The framework pursues an MVC (Model-View-Controller) design and incorporates vigorous formats, an incredible Object Relational Mapper (ORM) and Ajax for the server and program. Organizations using TurboGears incorporate Bisque, ShowMeDo, and SourceForge.


**Web2py **is a free, open source Python framework for web application development. The framework accompanies a debugger, code editor as well as a deployment tool to enable you to build and debug the code, as well as test and keep up web applications.

It’s a cross platform framework that underpins Windows, Unix/Linux, Mac, Google App Engine, and different other platforms. It pursues the MVC (Model-View-Controller) design. The framework streamlines web application development procedure via a web server, SQL database, and an online interface. It enables clients to build, revise, deploy, and manage web applications via web browsers.

The key component of Web2py is a ticketing framework, which issues a ticket when a mistake occurs. This encourages the client to follow the mistake and its status. Also, it has in-built components to manage HTTP requests, reactions, sessions, and cookies.


Another interesting Python web framework is Bottle, which falls under the class of small-scale frameworks. Originally, it was developed for building web APIs. Also, Bottle tries to execute everything in a single document, which should give you a short perspective on how small it is designed to be.

The out-of-the-box functionalities include templating, utilities, directing, and some fundamental abstraction over the WSGI standard. Like Flask, you will be coding significantly closer to the metal than with a full-stack framework. Regardless of their, Bottle has been used by Netflix to create web interfaces.


Tornado is a Python web framework and offbeat framework library. It utilizes a non-blocking framework I/O and unravels the C10k issue (which means that, whenever configured properly, it can deal with 10,000+ simultaneous connections).

Tornado’s main features comprise of built-in support for user confirmation, superior quality, real-time services, non-blocking HTTP customer, Python-based web templating language, and support for interpretation and localization.

This makes it an extraordinary tool for building applications that require superior and a huge number of simultaneous clients.


Flask is a Python framework accessible under the BSD license, which is inspired by the Sinatra Ruby framework. Flask relies upon the Werkzeug WSGI toolbox and Jinja2 template. The main purpose is to help develop a strong web application base.

**Developers **can **develop backend frameworks **any way they need, however, it was designed for applications that are open-ended. Flask has been used by big companies, which include LinkedIn and Pinterest. As compared to Django, Flask is best suited for small and easy projects. Thus, you can expect a web server development, **support **for Google App Engine as well as in-built unit testing.


**Grok framework **has been created, depending on Zope toolbox for giving an agile development experience to developers by concentrating on convention over configuration and DRY (Don’t Repeat Yourself). It is an open-source framework, developed to speed up the application development process.

Developers can choose from a wide scope of network and independent libraries as indicated by the task needs. Grok’s UI (user interface) is like other full-stack frameworks such as **Pylons **and TurboGears.

The Grok component architecture helps developers lessen the unpredictability of development by availing views, content objects, and controller. Grok, likewise, provides the building blocks and other essential assets required to develop custom web applications for business needs.


**BlueBream **is also an open source web application framework, server, and library for website developers. It has been developed by the Zope team which was formerly known as Zope 3.

This framework is best suited for both medium and substantial activities apportioned into various re-usable and well-suited segments.

**BlueBream **relies upon Zoop Toolkit (ZTK). It holds extensive periods of experience ensuring that it meets the main essential for enduring, relentless, and adaptable programming.


Though there are many python web development frameworks that will be popular and in-demand in the coming years, especially in 2019, every framework has its own pros and cons. Every developer has different coding styles and preferences. They will assess every framework as per the requirements of an individual task. In this way, the choice of python web development framework will change from one developer onto the next.

The above-listed are some of the Python frameworks that are widely used as a full-stack backend web application development. Which one are you picking for your next project? Do let us know in the comments section given below.