One of the most frequently discussed topics in Agile and Scrum circles is how to write user stories.  Technically, there is no one way to write a user story, however, there are widely accepted best practices.  This article discusses those best practices and the six most common mistakes developers make when writing user stories.

User Stories Compliment Scrum

User stories (and epics) are not part of the Scrum framework.  User stories are one of a number of complimentary practices or techniques many Agilists erroneously believe are part of Scrum.

“Adding on” practices that support the framework and promote agility is an intentional feature of Scrum.  As expected for any framework, we can add anything to Scrum as long as it does not contradict or undermine the framework.  Take away any element of the framework itself, and you are no longer practicing Scrum.

User Stories are Requirements

User stories are, in essence, functional requirements.  Functional requirements specify what a product/system/solution must do to satisfy business or mission needs.  In other words, what functionality or capabilities will the system include to provide business or mission value?  Traditional functional requirements are written from the perspective of what the system must do:

The system shall <do something>

For example:

The system shall allow users to upload xyz reports.

User stories are written from the perspective of what users need from the system to accomplish an outcome.  The most popular user story template is:

As <a user, role, or automated client> I want <some capability> so that <desired outcome>

This way of writing requirements puts the user front and center and tells us: (originally posted here)

• Which specific user, role, or automated client needs the capability or feature:  User Stories serve as reminders for future conversations.  They are not meant to document requirements in detail.  User Stories tell us the types of users we need to talk to or learn more about.
• The business or mission capability the user needs:  User Stories are written from the perspective of the business or mission capability a user needs to accomplish a desired outcome.  The resulting software functionality will enable the accomplishment of that business or mission outcome.
• The desired business or mission outcome the capability or feature will enable:  User Stories answer what tangible business or mission outcome will be achieved as a result of using the implemented feature.  The outcome is typically the execution of a business or mission process or task.

Well-Written User Story Example

Below is an example of a well-written user story: (originally posted here)

As a payroll analyst, I want to upload xyz reports so that I don’t have to manually input their contents.

We now know who needs the upload capability and for what purpose.  The role of the user is important because it alludes to the kind of data we are talking about: payroll data.  The outcome lets us know that the system is expected to do something with xyz report data, so this is not just an archival function.  User stories are reminders of further conversations about what is needed, and this user story identifies the user to talk to, what they need, and why.  This is enough information to get the conversation started.

Acceptance Criteria

It is not enough to know what the system must do.  How would we know if the resulting functionality achieved its business or mission intent?  Also, how well must resulting system functionality do its job?  To be more specific, what behaviors and performance characteristics (Non-Functional Requirements (NFRs)) must the functionality exhibit to address user needs?  User stories address these questions via acceptance criteria.

Acceptance criteria are the results or outcomes the functionality must achieve when executed.  We demonstrate adherence to acceptance criteria through testing.  Acceptance criteria serve as test criteria for the user story.

Well-written acceptance criteria are testable.  That means that the result is not left to interpretation.  The feature either delivered expected results or did not.  The behavior and performance the feature demonstrates should contribute to (or not degrade) overall system-level behavior and performance.[1]

Acceptance Criteria Example

Acceptance criteria for the user story example above could look like this:

1. The user can upload xyz reports from their workstation
2. Acceptable file types for upload are .xls and .pdf
3. The user can upload a mix of multiple files of either type at once
4. Total file upload size cannot exceed 30 MB
5. The user is made aware of successful and unsuccessful uploads
6. The user can access data ingested from the files they uploaded

INVEST Criteria

Like any requirement, user stories must be well-formed.  Well-formed user stories adhere to the INVEST criteria. They are:

Six Most Common User Story Mistakes

The following are the six most common mistakes developers make when writing user stories:

Learn how bad user stories lead to bad value delivery

Mistake 1: Writing user stories as tasks

As explained earlier, user stories are requirements.  A product backlog is not a list of to-dos for developers.  User stories document the functional scope of the solution from the perspective of its users or clients (human or automated).  User stories are business or mission facing.  Both business/mission stakeholders and developers should be able to understand the capabilities described in each and every user story.

A user story that reads like this:

As a developer, I need to build an xyz report upload capability.

places the focus on what the developer needs to do rather than what the user needs.  We lose the context behind what the xyx report upload capability needs to be, for whom, and why.

Worse is this example:

As a developer, I need to install and configure a SQL database.

In this example, we don’t know what the database is for.  On its own, a database is not a business or mission facing capability that users can use.  It is a component.  Agile value delivery is based on complete and valuable features, not on delivering the individual components that make up features.  Along with being requirements, user stories represent the features developers build to satisfy each requirement.

Mistake 2: Writing user stories from the perspective of the system

A user story like the one below reads like a traditional requirement or “shall statement”:

As a system, I need to provide a way to upload xyz files.

Rather than describing what the user needs to accomplish a desired outcome, this story describes what the system must do.  Again, we lose the context behind the capability.

Mistake 3: Leaving Out the “So That” Clause

More often than not, developers omit the “so that” clause from their user stories.  Doing so omits important context about what the user wants to achieve with the resulting functionality.  Developers should use that context to help define feature scope and identify larger stories in need of decomposition.

Defining Feature Scope Example

Look what happens to the scope of our original user story when we change the “so that” clause:

User Story Decomposition Example

Understanding the “so that” helps us ask better questions and tease out details that may change our understanding of a story’s scope.  For example, the archival process may actually involve multiple workflow steps:

• Step 1: Specify for how long each xyz report needs to be archived (Less accessible but cheaper cloud storage could be used for longer term archival needs)
• Step 2:  If the system flags any of the uploaded files as duplicates of previously archived files, they will not be uploaded.  The user will receive a message letting them know which files are duplicates.
• Step 3:  Ensure all uploads are successful.

Mistake 4: Not Writing Acceptance Criteria

As stated earlier, acceptance criteria define how we know that the functionality developed to satisfy a particular story achieves intended outcomes.  Acceptance criteria help inform development of automated tests and manual test cases which verify that the functionality fulfills functional and non-functional requirements.  They also help customers and end users validate that the functionality addresses their business and mission needs.

Mistake 5: Making Stories Too Big

In keeping with the INVEST criterion of keeping user stories small, and Scrum’s emphasis on breaking up work scope into Sprints, Scrum teams size user stories so they can complete them in a single Sprint.  A story that would take longer than a single Sprint to complete is considered an epic.

When development teams routinely fail to finish user stories within a single Sprint, it indicates that they are experiencing difficulty determining how much work they can realistically accomplish within a Sprint.  If user stories remain open Sprint after Sprint, the amount of unfinished work eventually overwhelms the team, causing them to miss commitments and deliver lower quality implementations.

Mistake 6: Making Stories Too Small

It is also common for teams to write user stories that are too small.  This usually happens when developers try to specify too many details across a large number of user stories.  Since user stories are requirements, make them implementation agnostic.  Do not write user stories that include implementation and design details or work tasks.

Conclusion

User stories are a widely used practice in Scrum, despite not being a part of the Scrum framework, because they are useful.  They are useful in:

• Promoting user-centric software development
• Minimizing the amount of documentation created by fostering direct communication between development teams, project sponsors, stakeholders, customers, and end users
• Improving team throughput (velocity) by breaking down work/feature scope into manageable pieces that promote “flow”
• Enforcing traceability between requirements, resulting functionality, and testing and validation

Writing user stories is more of an art than a science.  By consistently applying the recommendations and avoiding the mistakes explained here, you will develop an instinct for writing great user stories.

---

[1] https://agilecheetah.com/handling-non-functional-requirements-in-agile-projects/#User_Story_Acceptance_Criteria, accessed 8/20/2022