Story Quality Add-On for JIRA

Story Quality Add-On Logo

Welcome to Story Quality Add-On for JIRA – "It's time to get your story straight!"

As a development team,

we want to have user stories of decent quality,

so that we can work more efficiently.

Sounds familiar? If so, please read on.

Introduction

Background

User stories in agile development are the foundation of a development team's work. They have a huge impact on every aspect of the development process: "the business" (as in requirements), "the project" (as in schedule and management), and "the software" (as in implied technical details).

Stories actually are the requirements, and they are also the building blocks of project schedule. It's easy to understand their utmost importance.

On the other hand, stories are also very narrow vertical slices of way bigger and more complex systems involving a lot of business and technical considerations and dependencies. These systems need solid foundations, architecture and design, and proper dependency analysis, to work as expected.

This vertical slice nature means that the information in user stories about the structure of these systems can be very limited, and proper understanding of these structures is unfortunately neither encouraged, nor facilitated, by the use of user stories. This gets even more emphasized and riskier when user stories are almost the only source of information.

Motivation

Therefore, producing and working with user stories of appropriate quality is critical for development teams. Unfortunately this is often not the case. Development teams, and especially developers, tend to suffer from having to deal with suboptimal or outright useless stories. There is a need for common understanding of the quality of their stories.

Risk and complexity can be reduced, and the team's efficiency and mood can be improved, by having stories of good quality.

About the add-on

The Story Quality Add-On for JIRA checks and shows the quality of user stories. Its purpose is to help development teams identify and improve low quality and not-yet-ready stories, and possibly avoid starting progress on them. The add-on consists of a custom field and a workflow validator.

Important: It is assumed that the team is using JIRA in a disciplined way and estimating, that is, always specifying proper summaries and descriptions, the Story Points and the Business Value, and using sprints, versions, epics, labels, issue links, comments, and voting.

Custom field

The Story Quality calculated field displays a rating of the overall quality of user stories. The field is sortable and searchable, and the rating is an integer value between 0% and 100%, based on different criteria consisting of the INVEST principles and other indicators. The overall rating is a weighed average of these indicators discussed in detail in the Indicators section.

Story Quality field on the issue view page

The field is searchable with number range searcher

The field is sortable

A greater value indicates a more concise, complete, precise, and clear user story. The general idea is that the closer this value is to 100%, the more likely it is that the story is ready to start progress on, resulting in a more efficient process.

In short, this rating gives team members an understanding of the quality and readiness of their stories.

The field is automatically added to all screens that have a field called "Story Points", if the issue type "Story" is available in JIRA. This is a reasonable guess to find all screens showing user stories.

Workflow validator

The Story Quality validator blocks all "In Progress" or "Start Progress" transitions for non-administrator users (by default) for user stories that have insufficient quality rating, that is, points less than the minimum specified for the project. This helps ensure that the team is working only on stories that are ready for development.

Workflow validator in action

The validator's minimum required points can be configured manually by project administrators for every project in the project configuration section. To make sure that usual workflows are not affected immediately, it is set to 0 by default.

Project configuration for Story Quality add-on

Indicators

The indicators are rating the quality of a story (a JIRA issue of type "Story") based on different criteria. These criteria are designed from a developers' point of view, because their work is impacted first hand by the quality of the stories.

An indicator is calculating a point between 0% and 100% (inclusive), where 0% means the lowest, and 100% means the highest quality. The calculation can be any mathematical formula, but most indicator implementations are starting with maximum points (100%) and then giving penalty points for problems they find.

Detailed indicators on the issue view page

INVEST

"The INVEST mnemonic was created by Bill Wake as a reminder of the characteristics of a good quality user story." (Wikipedia)

The following six indicators are inspired by this well-known model for user story quality checks.

Independent

"The user story should be self-contained, in a way that there is no inherent dependency on another user story." (Wikipedia)

The idea is that a developer should be able to fully understand their task by reading only the user story, meaning the JIRA issue in question, without having to consult other sources, including too many attachments. This indicator:

Examples: a story with no dependencies and 10 attachments will have 50% rating, but 0% if it has any unresolved dependencies.

Negotiable

"User stories, up until they are part of an iteration, can always be changed and rewritten." (Wikipedia)

This means that the story should be described and discussed properly. This indicator:

Examples: a story with description and comments will have 100% rating, but 0% if any of those are missing.

Valuable

"A user story must deliver value to the end user." (Wikipedia)

JIRA has a field called Business Value, which is a numeric value indicating the business value delivered by the user story. Teams not currently using this field should consider using it. If the value of this field is not defined for the story, then a full 100% penalty is applied.

Examples: a story with Business Value specified will have 100% rating, but 0% without it.

Estimable

"You must always be able to estimate the size of a user story." (Wikipedia)

JIRA has a field called Story Points, which is a "measurement of complexity and/or size of a requirement." Teams not currently using this field should consider using it. If the value of this field is not defined for the story, then a full 100% penalty is applied.

Examples: a story with Story Points specified will have 100% rating, but 0% without it.

Small

"User stories should not be so big as to become impossible to plan/task/prioritize with a certain level of certainty." (Wikipedia)

This indicator tries to determine how easily the user story fits into the planned sprint or version. To be able to calculate available and necessary work hours, the following criteria must be met:

If any of the above is false, then the calculation cannot proceed, and the indicator gives a rating of 0% because of the uncertainty.

Otherwise, the point is calculated as follows:

Examples: a story which has no unique sprint and no unique fix version defined will have 0% rating; one which takes 75% or more of the available time will have 0% rating; one which takes 62.5% of the available time will have 25% rating; one which takes 50% of the available time will have 50% rating; one which takes 37.5% of the available time will have 75% rating; one which takes 25% or less of the available time will have 100% rating.

Testable

"The user story or its related description must provide the necessary information to make test development possible." (Wikipedia)

This indicator is focusing on acceptance testing, so it is checking the existence of acceptance criteria. This indicator:

If none of the above is true, then a full 100% penalty is applied.

Examples: a story with acceptance criteria defined in either a separate field or inside the description will have 100% rating, but 0% without it.

Other indicators

There are other properties and fields of a JIRA issue that make the work of developers easier. The following indicators are checking various useful aspects of stories that don't necessarily fit into the INVEST model.

Clarity

This indicator is checking the overall clarity of the story. It might give the following penalty points:

Examples: a story with too short summary and proper description will have 50% rating; one with too short summary and too short description will have 0%; one with summary "Implement backend" will have 0% (even with proper description); one with summary "Implement coffee machine" and proper description will have 50%.

Relevance

A user story created long ago might not be relevant anymore. If a story is created more than 20 days ago, then penalty points apply: five points for each additional day.

User stories that are not updated recently are getting irrelevant or they are not maintained properly. If a story is updated more than 20 hours ago, then penalty points apply: one point for each additional hour.

Examples: a story created 10 days ago and updated 60 hours ago will have 60% rating; one updated more than 120 hours ago will have 0% (even if it's created lately); one created more than 40 days ago will have 0% (even if it's updated lately); one created 10 days ago and updated 10 hours ago will have 100%.

Additional Info

Checks the presence of other useful field values. The following penalty points apply:

Examples: a story with no epic, assignee, fix, and labels will have 0% rating; one with all of these defined will have 100%; one with epic and assignee defined, but no fix version or labels, will have 50%;

Votes

Checks the number of votes for an issue, assuming that the team is actually using votes. There should be minimum 3 votes for full rating. Penalty points, if there are less than 3 votes: 100% / 3 for each missing vote.

Examples: a story with no votes will have 0% rating; one with one vote will have 33%; one with two votes will have 67%; one with three or more votes will have 100%.

Final words

Where do I get it?

You can download the add-on from the Atlassian Marketplace.

Contact and feedback

This add-on was developed by Patrik Varga, and inspired by real-life experiences. ;)

Please feel free to contact me in e-mail at varga dot patrik at gmail dot com with suggestions and any other feedback.

Reach me at: @patrikvar, my blog, LinkedIn.

Logo credits

The end

Story Quality Add-On for JIRA – "It's time to get your story straight!"

Copyright (c) 2015, Patrik Varga. All rights reserved.

This README is licensed under CC BY 4.0.