Three Commonly Left Out User Story Essentials

User stories are one of the most important ways that Agile teams generate just the right amount of documentation to align everyone on what to build. They are also one of the most misused techniques in the agility toolbox.

Here's the general format:

As a ____, I want to so that I can.

We expect a user story to describe the interaction of the user and the system, to help us understand the value provided to the user, and to provide clear criteria that we can observe when the story is done.

Sometimes user stories don't meet the expectations above by leaving out their most essential aspects. Here are user story essentials that some teams don't include and best practices for making sure that crucial information is included to meet user story goals.

Missing essential #1 The user and/or problem definition is missing.

When user stories begin with statements like the ones below, it's usually a red flag:

• As a developer, I want to create a Database.
• As a developer, I want to create an API.
• As a developer, I want to implement a UI.
• As a developer, I want to verify OAuth credentials.

The user is missing in the above examples, and meeting the value required of the user should be at the center of the story.

Best practice #1: Identify the user and what the value is.

Who are you creating the database for? Who will use the API? What can the user do with the UI? These are all questions to think through. To gain a clear picture of the user, consider creating personas that you can refer to in your stories so that he or she is the central focus of your efforts.

Many times, we don't go far enough in making the leap from a technical requirement to the value that a technical requirement provides. What benefit will the user receive by using the database, the API, or the UI? What value do these technical constructs enable for the user? Let's say that your Product Manager tells you that your "Verify OAuth credentials" story isn't important and de-prioritizes it. The PM may bump the story up in the backlog if the story is written: "As a user, I want to securely log in so that my information is not stolen, read, or modified by attackers, hackers, or other entities."

Missing Essential #2: Unclear acceptance criteria; acceptance criteria are an implementation description.

The intent of acceptance criteria in a user story is to spell out what the user can do and/or observe to gain value. User stories as well as acceptance criteria are written from the user's perspective because they are the main tool that teams use to communicate with business partners to determine if they are delivering the right value in the right way.

If you are a business (non-technical) person, would you be able to tell if the right value is being delivered in the following user story?

API Call Using ID Token
Implement UI to:

• Capture user ID and Password
• Call User ID Token API, with User ID and password, to get user ID token
• Store the ID token in the memory for later use to make subsequent API calls (store the ID token, against the user ID to ensure the right ID token is passed to the right user)
• When user logs out, nullify the ID token of the user
• User successfully logs in and gets ID token ready for API calls
• ID Token is stored against the User ID (User ID | ID Token)
• Display appropriate error message when token expires

Best practice #2: Focus on WHAT rather than HOW.

Below is the user story from above written so that we can use it as the communication tool it is meant to be:

As a user, when I attempt to log in to the system after my login has expired, prompt me to log back in so that I can access the system to complete my work.

• Verify that when the system times out, when I attempt to log back in, I am asked to log in because my session has timed out.
• Verify that when I'm asked to log in, I can supply my username and password and be logged back into the system.

To get out of implementation mode in stories, first, think of the user, and then ask yourself the following:

• How will this story be tested?
• What steps does the user take and what should he see?
• How will this story be demonstrated in Sprint Review to our stakeholders?

The HOW for the story can be documented as tasks. Ultimately, we should know WHAT the story is to deliver.

Missing essential #3: The story is not vertically sliced and reflects a part of the software development life cycle.

This anti-pattern commonly shows up in organizations where cross-functional teams are new or there are knowledge silos. User stories are written according to the software development life cycle or a component. Here is a collection of stories that send up a possible red flag:

• Create a database
• Create a log in API
• Implement the log in UI
• Test the log in

Best practice #3: Focus on a small piece of value to be delivered.

The key to developing vertically sliced stories is to identify a small piece of value that can be developed all the way through the life cycle.

The value of any system flows through the interaction of its components. User stories are introduced in order to develop a small piece of value through the full life cycle. A little bit of design, a little bit of development, and testing are all included in that story.

Your stories may have to get smaller to accommodate vertical slicing, but that's the point. User stories are the mechanism to foster conversations around "how much". Maybe you need to build some technical "runway" so the "create an API" story is placed in your sprint. In the end, it's important to remember that developing vertically a little bit at a time will increase feedback loops and allow teams to discover issues earlier in the development lifecycle.

Include the User Story Essentials

Shaping a user story by the user it's for and the value that's provided in a potentially shippable way are foundational aspects of creating a good user story. Keeping in mind that user stories are not tasks that you need to do, but expressions of your customers' needs, will help your team explore the right problems to solve.