How to write good User Stories

Good user stories (US henceforth) are a key element in the Agile methodology – It is from the US that we define the functionalities of the application that we are building.

The agile methodology is based on the principle that the specifications of a project should be easily understandable and maintainable. The purist waterfall model had an extremely complex specification model: IEEE Ansi 830 (1993, Rev 1998).

The principles of agile development changed this practice in favor of the user stories. The US are not as exhaustive as the classic requirements, but they offer information that makes much more sense, since good user stories define functionality.

How to write good User Stories

Good user stories must offer an actor, an objective, a context, a motivation and a way to validate it – and allow both the project manager, the user and the developer to elaborate and discuss it in order to align to develop the desired value.

When we develop good user stories it should be very clear that a user story is a living entity, which starts from an initial wording to open a conversation between client, manager and development team. The fact that this conversation often does not occur should not lead us to believe that a user story is immutable throughout the project.

The models of development based on good user stories are less exhaustive but they help a lot to define the set of functionalities to be implemented from the point of view of the user, and therefore, that the result of our development meets the needs of our client.

Ideally, good user stories should follow the model INVEST:

• “I” ndependent – Independent of other user stories
• “N” egotiable – There must be conversations between client and development team, flexibility, not a closed contract
• “V” aluable – Each user story must add value to the product
• “E” stimable – Each user story must be able to be expressed, in a reasonably approximate way, by the development team – but in time, in complexity in relation to the others (story points)
• “S” mall – Each user story, ideally, must fit in one iteration (sprint). If it does not, it is strongly suggested to break it down into parts.
• “T” estable – Each user history must be able to be validated.

Parts of a User Story

The US are formed by the following parts:

• Title
• Description
• Criteria of acceptance
• Subsequent discussions

Title

The title of a US follows a very definite formula:

• AS <role>
• I WANT <objective>
• FOR <motivation>

The user history defines a functionality, since in a sentence it must make clear WHO (role) performs an ACTION (objective) to satisfy a NEED (motivation).

Some example user stories:

AS a user I WANT to be able to search for transactions TO be able to see unnecessary expenses in my account in a period

AS a user I WANT to access the nursing agenda in a secure way TO use its functionalities

The title of a user story must map a functionality of our product or software

When we are writing user stories, it is a good practice to also use characters instead of roles, since they give even more context, for example:

AS a user I WANT to be able to show the list of visits TO be able to manage the arrival of patients, and management of waiting rooms

vs:

AS a nurse I WANT to be able to show the list of visits TO be able to manage the arrival of patients, and management of waiting rooms

With the simple change of user by nurse we are giving much more context to our user history, and we make it much more readable for any type of non-technical personnel.

It must be remembered that the title of a user story must map a single functionality of our product or software.

Description

The description of a user story helps to give context to that story. The description may contain a small explanation of user flows, some use case, extreme cases and in general any explanation that helps to better understand the title. The description should not be a bible, and a picture is worth a thousand words, elements such as links to design pages are welcome, as well as screenshots that help clarify what is being expressed.

A good description of a User Story will contain these elements if available:

• Context: Provide application and use context to the developer and user, to improve the understanding of the user story title.
• Links to the mockups or design: They are a great help to understand how the functionality in the user story is to be mapped in the application.
• Constraints: Things that all the actors involved in the user story must take into account (navigation constraints, design constraints, use cases, or business flow cases).

Acceptance criteria

Along with the title, the most important part of a user story. The acceptance criteria are a set of conditional use cases that validate the implementation of our user story. Even today there are teams where the acceptance criteria are not used – In my opinion it is a big mistake. The acceptance criteria are fundamental, since:

• Help the developer to correctly implement the task
• In TDD the acceptance criteria must directly map to functional tests
• Following a strict TDD, the implementation should start with them
• They help the QA staff to give the OK to consider the user story finished
• The acceptance criteria must define, together with the title, the functionality to be implemented

The QA staff, ideally, should validate that all of them are met to give the OK to go up to production.

In general, the acceptance criteria must meet the following characteristics:

• ATOMICITY: They must have 2 unique results: SUCCESS or FAILURE (there is no term “partial success” – an acceptance criterion must always give us a GREEN or RED)
• NON AMBIGUOUS: They must be interpreted in only one way by N people (not worth something like “The form should be painted a cheerful color” – although worse things have been seen 😉 )
• VERIFIABLE: They must be written so that they are quickly verifiable by the client
• COMPLETE: The set of acceptance criteria should include all functionality requirements

As an example:

AS a user I WANT to access the nursing agenda in a secure way TO use its functionalities

Criteria of acceptance:

• The username MUST have value, otherwise a relevant error message will be displayed
• The username MUST be in the form of an email, otherwise a pertinent error message will be displayed
• The password MUST have value, otherwise a pertinent error message will be displayed
• The user name MUST exist in the database, otherwise a pertinent error message will be displayed
• The password MUST match the one associated with the user name in the database, otherwise a pertinent error message will be displayed

If the user and password are correct, the user can proceed to the application.

Many times acceptance criteria may seem trivial or unnecessary, but being thorough with them at the time of writing the US is the best way to fully develop functionality.

Subsequent discussions

Someone defined the user stories as “an invitation to a conversation“. In an ideal world, with unicorns and rainbows, we would have great clients who have super-clear the idea of what they want from the beginning, they would explain it to us clearly and no detail would be left.

But that does not happen – period

A user story will normally open a discussion between development team – PO and client.

Normally, user stories do not change conceptually and those conversations are what make them more detailed. The same happens with the set of acceptance criteria.