Ten quality attributes for better user stories

Learn to Write Better User Stories

What are user stories?

A user story is a placeholder for a conversation, a phrase or few used by Agile software development teams to describe valuable functionality that they intend to work on.

The user story is a means of communication (and a trigger for further communication).

User stories are a means of succinctly communicating the user-oriented functional needs of software. They are a shorthand, high level way of describing software requirements. They are used on Agile software work and are designed to be a stimulus for a conversation. They are often the only written form of the requirements.

User stories should be written by someone with a “user perspective” not a technical perspective. They should describe functionality and value that the team is expected to deliver to the user. When we write a user story, we are both acquiring and sharing knowledge.

User stories matter

No substantial software project will be delivered on time and on budget if it starts with poor quality requirements or user stories.  Furthermore every word of the user story matters.  Inappropriate words, can lead to misinterpretation, waste and rework.

Creating high quality stories

The wonders of the English language give us many ways of expressing the same thing. This flexibility leads to potential differences in understanding.  When two readers of a user story can reach a different understanding of what the words mean, we have a misunderstanding.  And misunderstanding likely to to lead to a software defect.

How long should they be?

Shorter is generally better.  We have seen stories as little as two words and as much as a page of text. Generally, shorter is better, but be careful not to miss out critical functionality.  We recommend 5-50 words depending on complexity (excluding the so that statement).

Who Writes User Stories

Ideally the author of the user stories is a product owner who has extensive experience in the role of the customer or end user.  Sometimes this is not practical and the author is a proxy for the end user, typically a Business Analyst (BA). The BA creates the first edition of the story, which is later discussed and refined by the team.  Once there is a common understanding of what it really means.  It can then go forward to be worked on.  The challenge is to reach a clear and common understanding quickly and with few words.

Higher Quality User Stories Will Avoid Bugs.

Many software teams do not appreciate just how important it is to work from good quality requirements or user stories. Commonly 20% or more of all quality problems with software are caused by problems with requirements.

Source of Defects

Start with the “Who, What and Why”

The functional need and business justification are the most fundamental aspects of good user stories. By this we mean “Who, needs to do What and Why”. Who is the user (human or connected system), what is the data handled and moved, and why is what follows the “so that” in a user story. Focus on these and avoid the how (exclude design statements).

Better user stories will reduce rework

For any development team, entering a sprint with a poor user story may be agile, but it’s certainly not lean. It is well worth spending time on getting your users tories to be as good as you can, as clear as you can to minimise misunderstandings. Misunderstandings will lead to costly rework.

What’s the difference between user stories and use cases

We’ve already said plenty about user stories. A use case is a list of actions or event steps typically defining the interactions between a role (referred to as an actor) and the system. User stories are typically a subset of a use case. A user story typically describes just one of the interactions that may be described in a use case.

Automated testing of user stories

The quality of user stories has been ill-served by automation. In fact, prior to our release of ScopeMaster®, we have been unaware of any tools that can help you improve the quality of your user stories. There are a few products on the market now that approach some of the functionality of ScopeMaster, but none come close to offering such a comprehensive and valuable automated analysis of user stories for QA, estimation and test generation.

Functional Basics vs Acceptance Criteria

Remember that the core description of user functionality precedes the acceptance criteria. The acceptance criteria are an elaboration of, and depend on a clear functional set of statements from a user perspective.

Realtime requirements testing and improvement suggestions

ScopeMaster performs realtime analysis, testing, correlation and sizing from the text of user stories. The feedback provided by ScopeMaster will help you improve the wording you use. You’ll achieve, clearer, more concise, complete, consistent requirements. Focus first on Who and What. ScopeMaster generates and runs both static and dynamic tests against each user story, that will help find and warn you of potential problems. It performs a level of automated requirements scrutiny that has hitherto been unavailable in the software industry.

User Story Quality Test Results

Not only does ScopeMaster® examine and analyse the language of each user story, it also cross references every story against all of the others within a set – it detects inconsistencies, omissions and duplicates. This helps you to refine your requirements much faster. The smart interface of ScopeMaster dynamically identifies missing stories and makes it even easer to add them.

Handling Infinite Possibilities

ScopeMaster overcomes the vast range of possible expressions of requirements by using a form of Artificial Intelligence know as Natural Language Processing. This allows you to express your user stories in terms specific to your industry; the tool requires no prior training.

Create better user stories faster

ScopeMaster scans user stories (or software requirements) for appropriate language that is suited to software requirements and that will help you write clearer, concise, consistent, complete and unambiguous stories.

Detects potential defects

INVEST – is a commonly used checklist for agile user story quality.

  • Independent *
  • Negotiable / Concise *
  • Valuable
  • Estimable *
  • Sized *
  • Testable *

*ScopeMaster helps the author find and fix these problems (over 50% of all requirements defects).

Our own preferred, more comprehensive checklist for writing better usr stories is this:

  • Unambiguous / clear *
  • Measurable / Functional *
  • Concise *
  • User oriented *
  • Testable *
  • Consistent *
  • Whole and complete *
  • Unique *
  • Design Free *
  • Traceable to business value

ScopeMaster helps with 9 out 10 of these quality criteria to some extent, and overall it will help you find over 50% of potential requirements defects, pre-coding.

In our own tests on over 250,000 user stories gathered from over 100 sources, we found that ScopeMaster exposes 0.3 -0.7 defects per CFP (excluding inconsistencies, which we expose but cannot calculate), whilst the typical observed in industry is just under 1 defect per FP (Capers Jones). There we have it, real data showing that ScopeMaster can help you write better user stories.

By using ScopeMaster interactively at the beginning of your project to improve your user stories, you can put your software work onto a more solid quality foundation right from the start – before design and coding is underway. You can continue to refine the stories or throughout the development process, as part of your product backlog refinement. The great thing is that you will have avoided rework by starting with a better foundation of writing user stories of higher quality.


First and foremost a user story is a means of communicating.  It needs to transfer knowledge about some or all of the following:  the need, the requirement, the functionality, the outcome, the purpose of the requirement.  If it fails to provide clear intent, then it will lead to misinterpretation that can in turn lead to bugs.

Learn to write user stories that developers and testers will love

Let ScopeMaster help you write user stories that your team will find easy to build.  Those stories will be clear, sufficient, consistent, complete, sizeable, testable.  Everyone can become an author of great user stories.

Alexander Cowan Refined user story

Alexander proposes steps to achieve a good quality user story, proposing the following as a “refined” user story.

‘As the HR manager, I want to create a screening quiz so that I make sure I’m prepared to use it when I interview job candidates.’

We ran this through ScopeMaster in isolation and it instantly detected the primary functional intent and measured the size as 4 Cosmic Function Points.

Another useful source for the definition of a user story.

Mountain Goat Example

We also analysed the set of 238 user stories published by Mike Cohn

  • Time taken
    • 64 seconds
  • Quality assessment:
    • 54% unambiguous, sized at 629 CFP
    • 46% ambiguous
    • 233 potential omissions
    • 28 potential duplicates
    • Over 20 inconsistencies
  • Sizing / Estimation
    • 1161 CFP total size estimate.

User Task Focussed

User stories or requirements that are focussed on what the user needs the system to do to achieve a task will be more useful than a features list.

Art or Science

Art is subjective while science is objective, art expresses knowledge.  The application of the science in real world scenarios is typically considered to be engineering.

When we write a user story, we are both acquiring and sharing knowledge.

On one hand the user story is an acquisition of knowledge from the customer/user/product owner and on the other hand it is also an expression of knowledge for the team to understand and work on.

Common to both Science and engineering is measurement, whereas this is almost always absent from artwork.