Writing Great User Stories

writing great user stories ammeon

One of the most fundamental components of any agile project is the humble User Story. Originally billed as a “prompt for a conversation”, user stories are the basic building blocks of a team’s sprint backlog and the essential capture of the product increment. How to word a user story, how to break it down if it’s too big, and what not to do with user stories are common topics that arise in organisations.

Early experience

Back in the days of Extreme Programming (XP), my first exposure to user stories was as a high-level slogan alluding to some new functionality as a business need. I took to always carrying some blank index cards around with me, as these requirements could often be identified and expressed by customer-facing Product Managers informally as well as in planned meetings. In no time at all, I could be looking at dozens of index cards and uploading them to a computer. This was in the days before tools such as Trello and Jira. The act of sorting through those briefly worded cards was useful in assembling some kind of order, for instance aspects of functionality requirements that are very closely associated (in many cases overlapping or even duplicates, occasionally conflicting). In the spirit of their early billing, they of course prompted further sit-down conversations to really understand what was being sought and in particular – why.

Recommended wording

This has now been brought into the rules of how user stories are most often expressed in projects, with a syntax of:

“As a <type of user>, I want to <description of use case>, so that <explanation of why it’s useful>”

For example, you could compose a user story along the lines of:

“As an Administrator of the X system, I want to configure logging to send all information messages to a separate informational log file, so that the main log file does not get too cluttered”.

Disregarding whether this functionality is advisable, you can see that the point of it is to declutter the main log file. This is a requirement that is unlikely to survive intact beyond the first Backlog Refinement session that you have with the team, who as a group mind, will come up with much better solutions, now that it has been expressed.

One way of thinking is to consider that the user story captures the ‘what’ and the functionality that the team designs is the ‘how’. This leads to a mindset of the user story being the business need and what the team actually designs and delivers, is the functionality.

You will have noticed that I have been looser in my wording, talking of features, functionality and requirements as shorthand, however the previous statement is the most accurate. In discussions with a team, I sometimes speak of the required ‘behaviour’ of the system to help them to see it from the perspective of the user.

Becoming familiar with how your team prefers their user stories worded is important, which of course depends on what they may already be used to. For example, if they are an established team or if strong organisational conventions have built up. A convention such as wording user stories in the present tense is obvious once it’s pointed out to you, but at the time of initial capturing, you are still thinking in the future tense.

Going back to the log file example, the question arises as to how much detail do I have to put in the story description and what really should be implicit – for example, I don’t state precisely how this configuration step should be presented: should it be a true or false flag in a configuration file or a radio button on a configuration screen, or should the filling-in of an informational log file name be sufficient to configure the functionality? Or maybe after configuring the file name, you need to perform a logging restart to activate the functionality? In accordance with focussing on the ‘what’, my approach is not to detail such behaviour where for example, the presentation method clearly should align with the agreed UI framework and allowing the team to consult with their UI expert if genuine questions arise. For example, if the functionality can’t be implemented in a way that activates dynamically and some kind of restart is needed, or if reversing the configuration setting is problematic.

Thus, the typical user story might first have the “As a user…” one-line title and then some sentences as a description of the required functionality. Brevity in the description is always a plus because a description that runs for many paragraphs will lead to calls for it to be ‘broken down’ before anyone even reads it. However, required functionality can be complex and may need more text or diagrams to describe it fully.

Story sizing and planning good practice

Breaking down a story is a common call, and what is really meant is that a story is split into two or more user stories. The required balancing act is to make sure that each diced-up story is still a ‘story’ in that it delivers a genuine increment to the product (or to put it formally, conforms to the INVEST principle). For me, that generally means that the essential basic need is delivered and is usable. You can add stories to cater for other use cases. A big no-no is hiving off test activities to another story. This often arises when the user story is decomposed into tasks (or subtasks as the popular tool Jira calls them). I have seen many good established teams devising a standard set of subtasks as a kind of checklist, which they can then look at, for instance to see – does this affect the documentation or not? Another pitfall is where there is a desire to separate out the ‘front-end’ and ‘back-end’ aspects – my line is always that it must be a full bit of functionality. However, in the very first steps of a product’s development lifecycle, such an end-to-end target may be beyond what is achievable in a single iteration. In one project that I can remember, there was the need for a telecom messaging product to support a particular additional incoming messaging protocol. In the first iteration, I had a user story that spoke of “accepting well-formed messages and rejecting malformed ones”, so while the system didn’t yet actually process the new traffic, at least it could verify it.

Identifying stories such as the above, which are prerequisites for others, is very important for planning purposes. For example, you may have an application which is in the early iterations and doesn’t yet have support for multiple users or roles. Those stories will need to be well flagged before the pressure to deliver user-dependant features arises.

Another thought as you create user stories is to have them as reasonably small as possible so that they can be sustainably delivered in a single product iteration yet offering some real business or functional value. Some projects like to have a target that it is possible for a single user story to be completed by an individual within a very short amount of time, say one to two days. I’m not personally a big fan of this approach as I prefer to give a team something meaty to get stuck into rather than a bite-sized portion. This of course depends on the length of your iterations and the maturity of your team.

Going the other way and composing monster-sized stories only delays the Backlog Refinement because the team will immediately want to split them. This is quite correct as there is little point in having an iteration comprised of a single user story with the greater possibility of the iteration goal not being met (if the story fails to make ‘done’). A discussion on the definition of ‘done’ is for another day, as is the creation and inclusion of the Acceptance Criteria, but neither can be disregarded in any self-respecting article on user stories.


As with most things in your professional life, it gets easier with practice and in line with the agile pillar of Inspect and Adapt, honest feedback from your team soon aligns what you do with the efficient and effective running of your agile project.

Further reading


How can organizations help development teams maximize value delivery

Devinder Sharma
Product Owner | Ammeon

Creating an application template from an existing application

Ammeon | September 10, 2021

In this blog post we’ll be looking at how to take that running application and create an application template from it.  This will allow the whole application to form a simple repeatable deployment based on a few given parameters. 


Ammeon awarded Container Platform Specialist status by Red Hat

Ammeon | August 27, 2021

Red Hat have awarded us with Container Platform Specialist status. This has been awarded to us for our consistent high standards of Red Hat OpenShift delivery, as well as our specialist expertise and experience that we bring to projects. Ammeon has become one of Red Hat’s leading professional service partners across Europe and our work with OpenShift has been a major reason for this award. We design, build, deploy and manage OpenShift models for our customers across a range of …


How Can Flow Efficiency Improve Productivity

Ammeon | July 4, 2021

Flow efficiency examines the two basic components that make up your lead time: work and wait time.