How to write good User Stories in Jira: The Software House’s way

5 min

read

The Software House is revealing one of the company’s best-kept secrets! Do you know how to write good User Stories in software development? No? Well, then you’re in for a treat! In this article, we will present the so-called “Kuśmierz-Polak Method” which is TSH-original template to be used in Jira. 

What’s a User Story?

User Story is a way to define the product and describe its functionalities from a user’s point of view – what they need, what matters to them and what they look for in this particular product. 

That’s where Kuśmierz-Polak Method waltzes in. It’s a way of writing User Stories invented at The Software House by our Project Manager – Marcin Kuśmierz, and the Head of Node.js – Adam Polak. Originally, it was implemented during our work for Finnish company Arantio

Since then, it’s been thoroughly tested in multiple projects and we’ve proved that it’s:

  • clear and well-organised, making it easy to understand,
  • practical and useful, resulting in faster implementation of new features,
  • not only accepted but, in fact, universally liked by our developers.
Profesor Snape with caption what kind of sorcery is this?
Something management-related and LIKED by developers?

How does Kuśmierz-Polak Method look like?

The Software House’s magical way of writing User Stories consists of a few sections which fully define acceptance criteria. 

We’ve prepared a preformatted, ready-to-use template which can be copied straight to Atlassian Jira and then filled out. Isn’t that cool?

Keep in mind that this template is flexible and that-depends-friendly. Not every section is needed in every project – if you feel like something won’t be useful at all, you can easily delete the unnecessary sections. 

h4. Pre-conditions
*

h4. Post-conditions
*

h4. Requirements
*

h4. Normal flow
#

h4. Alternative Flow (Name)
#

h4. Data Inputs

h6. Form Name
||Field name||Type||Mandatory||Editable||Source of data||Validation||Comments||
|Name|Type|Yes|No|User Input|-|-|

h4. Messages
||Name||Type||Text||
|Name|Type|Text|

h4. Designs
*

Nee-nah! 🚨 Important notice: as you probably know, Jira is updating its interface right now. However, creating new tasks is still based on the old interface, therefore, the template above is also based on the old formatting. When the interface update is completed, we’ll update and adjust the template to new guidelines, so remember to save this article for later!

he-man with caption by the power of jira

Read more: Dear developer, why does your Project Manager suck?

What are these sections for?

As you can see in the aforementioned paragraph, Kuśmierz-Polak Method splits into a few sections – from pre-conditions to design. Don’t worry if you have no idea what they mean yet. Below we will thoroughly explain what every section needs and how will they help you in organising your User Stories. 

Pre-conditions

Describe all the conditions that must be met in order to use this feature in the first place. For example:

* User must have Administrator permissions
* User must be on a login page

Post-conditions

Here, you explain the expected effect of the feature you’re describing. So, it may look like this:

* Request has been created
* User has logged in

Requirements

If there are any additional requirements you need for this feature to work properly, this is the place where you write them down. For example:

* Before saving, the User should see a modal with confirmation
* City and Country should be selected from Google Maps API
* After adding a new User, an email with information about that should be sent to this User

However, it’s also important to enumerate the things which the client DOESN’T want when it comes to the feature. For example:

* Before saving, the User shouldn't see a modal with confirmation
* City and Country should be filled in by the User, not taken from the Google Maps API
* After adding a new User, no email should be sent

Pre-conditions, post-conditions and requirements are described using unordered, bulleted lists (*). It’s simply because the order isn’t important here. However, the following sections – where you describe the feature’s Normal Flow and Alternative Flows – use ordered, numbered lists (#).

Normal Flow and Alternative Flow

A flow is a series of steps which the user must take in order to get to the post-conditions described above. There’s a given number (N >= 1) of the feature’s possible flows. However, in most cases the number of flows equals 1 or 2:

  • N = 1: there’s only one flow (i.e. the Normal Flow) and no alternatives
  • N = 2: there’s one Normal Flow and one Alternative Flow

Normal Flow

Couldn’t be more straightforward. Normal Flow is the basic set of steps which the user must take to achieve the feature’s expected effect (i.e. to get to the post-conditions). It’s the flow that will be tested first by QA engineers. But that doesn’t mean you can just slack off and leave the entire work to the testers. On the contrary – you need to describe the step-by-step flow using sentences based on the Gherkin language, so start with words like “WHEN”, “THEN” or “AND”:

# When I fill in form 'Login form'
# And click 'Login' button
# Then I should be logged in
# And redirected to the Dashboard

As you can see, there’s a “Login form” input used in the example above. Worry not, we’ll describe it in the Data Inputs section later.

Alternative Flow

If there’s another possible feature’s flow, that means we’re dealing with Alternative Flows. But they’re no less important – QA engineers will also need to take a look at them to check if they 100% working. It’s a good practice to give specific names to Alternative Flows, for example:

Alternative Flow Error On Login
Alternative Flow Registration Needed

Now, let’s write a hipster… sorry – an Alternative Flow, using sentences based on Gherkin:

Alternative flow Invalid Credentials
# When I fill in form 'Login form' with invalid credentials
# And click 'Login' button
# Then I should see a validation message “Invalid credentials”

Data Inputs

In this section, you are going to describe all the forms needed for the given feature – end-users will fill them out later. The “Form Name” should be the same as in the flows above (Normal Flow or Alternative Flows), so in case of emergency, everybody could easily find the required Data Input quickly. For clarity, we advise presenting all the information in a table. You can see the example below: 

h6. Login form
||Field name||Type||Mandatory||Editable||Source of data||Validation||Comments||
|Username|Text|Yes|Yes|User Input|No|-|
|Password|Password|Yes|Yes|User Input|No|-|

After saving the User Story in Jira, the table will look something like that:

Now, what information you should definitely include in the table? They might slightly vary from project to project, however, the core categories are:

  • Field name – usually a placeholder
  • Type – text, radio button, password, etc.
  • Mandatory – yes/no
  • Editable – yes/no
  • Source of data – User Input (in other words, filled out by the user) or/and DB (extracted from a database). Pretty often it’s both DB and User Input because the user might be editing a form that has already been filled out by them before (with the previous record stored in the database)
  • Validation – what kinds of validation are needed in this form
  • Comments  – additional information, e.g., the radio button options or the checkbox text

Read more: A few tips on how to perform an effective Daily Scrum

Messages

This section will include all the possible messages the user will receive after a certain action. Yup, this is our favourite “incorrect password” popup when you’re desperately trying to remember what 18-year-old you could have set as a password to your Amazon account. Again, it’s probably the best to present them in the form of a table:

h4. Messages
||Name||Type||Text||
|Invalid credentials|Error|”Incorrect username or password”|

And this is how the table looks like in the User Story:

The information that you should include in the table:

  • Name – just like the aforementioned “Form Name”, this one should also match the names used in the flows (Normal Flow or Alternative Flows) for clarity and future research
  • Type – Success/Error, etc.
  • Text – the text of the displayed message

enters password - wrong - resets password - new password can't be your old password

Designs

Let’s not forget about Product Designers, after all, they are the crucial part of any software development project. No matter if we’re talking about UX or UI design, our creative workmates need some instructions too. 

In this section, you should simply provide your development team with an unordered, bulleted list (*) of designs needed by the team to properly implement the given feature. 

And, after creating design tasks for the UX/UI designers, you should paste all the necessary links here  – the good practice is one bullet point with one link for every task. Finally, all that’s left to do is connect all those tasks to the User Story using Jira’s functionality.

Make your User Story problems go away

We hope that now you’ll know how to write User Stories better and faster using Kuśmierz-Polak Method. We can assure you that after applying it to our company processes, a lot of organisational problems just disappeared and the work quality was very much improved. 

We realize that initially you’ll have to spend a few hours implementing our template in Jira, but the advantages of this solution will certainly be worth the hassle. It’s easily accessible by any team member, you’re not making people upset by introducing any additional tools (if you’re already using Jira), and you can simply copy-paste it when new projects arrive. What’s not to like? 

Estimate your project





or contact us directly at [email protected]

Thanks

Thank you!

Your message has been sent. We’ll get back to you in 24 hours.

Back to page
24h

We’ll get back to you in 24 hours

to address your needs as quick as possible.

Estimation

We’ll prepare an estimation of the project

describing the team compostition, timeline and costs.

Code review

We’ll perform a free code review

if you already have an existing system or a part of it.

Our work was featured in:

Tech Crunch
Forbes
Business Insider

Aplikujesz do

The Software House

Aplikuj teraz

wyślij CV na adres: [email protected]

CopiedTekst skopiowany!

Nie zapomnij dodać klauzuli:

Kopiuj do schowka Copy

Jakie będą kolejne kroki?

Phone

Rozmowa telefoniczna

Krótka rozmowa o twoim doświadczeniu,
umiejętnościach i oczekiwaniach.

Test task

Zadanie testowe

Praktyczne zadanie sprawdzające dokładnie
poziom twoich umiejętności.

Meeting

Spotkanie w biurze

Rozmowa w biurze The Software House,
pozwalająca nam się lepiej poznać.

Response 200

Response 200

Ostateczna odpowiedź i propozycja
finansowa (w ciągu kilku dni od spotkania).

spinner