DEV Community

Cover image for The Art of Writing Agile User Stories
Rammina
Rammina

Posted on • Updated on

The Art of Writing Agile User Stories

Have you ever thought of what a user would do with your application?

No matter how well-architectured the app you built is, if it brings no value to users, chances are, no one will use it.

In simple terms, user stories are brief, informal descriptions of a software feature told from the perspective of the users. These answer the "who," "what," and "why" of a single task/functionality in an application.

User Story Format

As a(n) <user type>, I want to <function> so I can <benefit>
Enter fullscreen mode Exit fullscreen mode

Example

As a customer, I want to view the list of menu items, so I can easily choose what food to order.

The user type answers the "who," the function refers to the "what," and finally, the benefit explains the "why" in a user story.

What Makes a Great User Story?

Now that you know the typical format for a user story, the next question that comes to mind is "What makes a great user story?". Your backlog should not be filled with stories that actually do not provide user value. If you do, you could waste a lot of time and effort planning for and working on tasks that don’t add much, if any, business value to your project.

INVEST criteria

Image by Andre Simones from one80agiletraining

INVEST

Fortunately, Bill Wake coined the term "INVEST" which serves as a reminder of what characteristics of a high-quality user story. INVEST stands for:

  • Independent: User stories should not be dependent on one another.

  • Negotiable: Should leave space for discussion.

  • Valuable: Must deliver value to the stakeholders.

  • Estimable: You should be able to estimate the size and scope of a user story.

  • Small: The user story should be small enough to easily plan and prioritize it.

  • Testable: You should be able to test the results of development.

Ideally, your user stories should have all of these characteristics, because they enable you to easily determine how each task fits into your project timeline. By following INVEST, it is much easier to decide which items you must fulfill first, and which ones can wait until later.

Examples of Bad User Stories

Examples of Bad User Stories

Image by Roman Pichler from romanpichler

Here are examples of bad user stories, and why they don't work:

As a customer ordering fast food online, I want to find previous food order lists so that I can see all the orders that I have.

Problem: The benefit/value is absent from this user story, because so that I can see all the orders that I have is just a re-statement of find previous food order lists.

As a QA tester, I want to have access to test plans so that when the product is finished, I know how to test it.

Problem: Users do not really care about test plans, they just want quality products.

As a Jam’s dining customer, I want various food item categories displayed in different colors: red for meats, magenta for grains, and olive green for vegetables and fruits—so that I can easily group my food items by food type.

Problem: The user story is way too technically specific and robotic. This not only fails to represent a user but also limits the creativity of the developers.

Examples of Great User Stories

Examples of Good User Stories

Image from justinmind.com

In contrast to the previous bad examples, here are the user stories that work well:

As a customer ordering fast food online, I want to find my saved food order lists so that I can reuse them for future orders, allowing me to order faster and more accurately.

As a Jam’s dining customer, I want items to have a custom item code so that I can quickly find an item on a screen.

As a logged in user, I would like a login timeout and log off after a certain amount of time so that I can have some protection against unauthorized use when my computer is left unattended

These user stories work well because they have the characteristics of INVEST:

  • their functionality is not dependent on other stories
  • they leave room for different implementation options
  • they add user value to the project
  • their scope and size can definitely be estimated by developers
  • they are small enough to be planned around and/or reprioritized against other stories
  • they can be tested

Completing a User Story

Now that you know how to make great user stories, you'd probably like to know when they are finished. A user story is completed when it meets its Acceptance Criteria and its Definition of Done (DoD). But what do these terms mean?

Acceptance Criteria vs Definition of Done

Image from agilemania

Acceptance Criteria

The Acceptance Criteria of a user story consist of the set of test cases that must be fulfilled to ensure that the software is working as intended. Like user stories, acceptance criteria should be written from the perspective of a user. They should be clear, concise, and easily utilized by the development team. Acceptance criteria should not be concerned about implementation, but only about which features should be present and included. Each user story will have different Acceptance Criteria based on its requirements.

Definition of Done (DoD)

The Definition of Done (DoD) is a list of requirements that a user story or Increment must adhere to for the team to call it complete. The DoD serves as a checklist that guides various pre-implementation activities such as discussion, estimation, and design. By ensuring that the DoD is followed, the team can minimize reworking on user stories.

Its difference from Acceptance Criteria is that DoD is common for all the user stories whereas Acceptance Criteria are applicable to only a specific user story.

User Stories in Agile/Scrum Environments

Notion board

Image by Nate Martins from Notion

In Agile/Scrum environments, a team would utilize user stories as part of their Product Backlog. Each story represents a single unit of functionality in a project, and a backlog contains multiple user stories. Many teams nowadays use issue trackers or tickets for listing user stories, while others still use sticky notes. As PBIs become higher-ordered in the Product Backlog, they tend to be broken down into user stories with more specific tasks listed.

Unlike a Product Backlog Item (PBI), a user story depicts more than just a specific requirement, change, or bug fix. Its focus is on the end-user and their experience. A user story is an increment that provides value to the overall product.

3Cs of User Stories

An Agile user story has three primary components, each beginning with the letter "C" hence the "3Cs":

  • Card
  • Conversation
  • Confirmation

Card
The "Card" refers to the written text of the user story and serves as an invitation to conversation. Typically, user stories would be written on index cards, hence the "Card" aspect. One benefit of this is to keep a user story concise but still provide enough information. It also allows a team to discover more about the user's needs through conversation.

The most common format of the user story "Card" is:

As a(n) <user type>, I want to <function> so I can <benefit>
Enter fullscreen mode Exit fullscreen mode

User stories do not necessarily have to follow this format, but it helps keep those three important things to mind.

Conversation

The "Conversation" is a collaborative interaction, usually in-person, facilitated by the Product Owner. This interaction involves all stakeholders and the team. It encourages continuous, incremental collaboration among the Agile team members by allowing them to have a shared understanding of a problem. The team will make adjustments to the "Card" based on the information gained from having the "Conversation." While these conversations are typically verbal, automated tests and documentation support them.

Confirmation

Finally, the "Confirmation" in a user story determines whether it's completed or not. It refers to the Acceptance Criteria which declare the story's requirements. The user story is only finished once the acceptance tests pass and the Acceptance Criteria are met. Typically, the Product Owner will have to verify the completion of the user story before it is considered "done."

Pros and Cons of User Stories

Pros and Cons

Image from heavencpa

Advantages of User Stories:

  • helps ensure that a functionality brings user value
  • follows Agile/Scrum core principles
  • makes it easier to organize software functionality, as it leaves out implementation details
  • allows team members of different expertise and backgrounds to plan an application more easily
  • encourages conversations rather than simply handing out document details
  • simple to prioritize and reorder, especially for product backlog items
  • easily understood by both clients and developers

Disadvantages of User Stories:

  • does not explain the "how?"
  • does not involve non-functional requirements (e.g. fault tolerance, performance, usability, modifiability)
  • user stories are not substitutes to business requirements
  • the lack of implementation details means that the processes could vary a lot from team to team
  • can be misunderstood and misused
  • can lose its original essence/purpose (especially in companies and teams that are "Agile" only for compliance purposes)

Frequently Asked Questions (FAQ)

Common Questions and Answers

Who writes user stories?

Anyone can write user stories. In an Agile/Scrum environment, the Product Owner is responsible for the backlog of all user stories. However, anyone in the entire team can make them. Solo developers can also utilize user stories to help guide them when building a project.

When should you write user stories?

User stories can be written anytime. Typically, a team will hold a meeting at the start of the project to create user stories to identify initial project requirements. It is impossible to identify all of them at the beginning, so the team will create user stories over the course of the project timeline as they discover more user requirements.

When is a user story completed or finished?

A user story is completed when it meets its Acceptance Criteria and its Definition of Done (DoD).

Do user stories replace a requirements document?

They don't, as they serve different purposes. A user story focuses on the experience and needs of users, while a requirements document goes into a lot of detail about features necessary for a project. User stories focus on the who, what, and why. On the other hand, requirements documents contain the what and how.

What are the differences between user stories and Product Backlog Items?

At first glance, they seem similar, but there is a key difference: User stories place an emphasis on the end-users and their experiences. On the other hand, a Product Backlog Item merely represents a specific change, requirement, or bug fix without being concerned much about the who.

Are user stories like pseudocode?

They are used differently. Pseudocode is mainly concerned about implementation details and how a developer would build a solution, and user stories completely leave out the implementation details in exchange for focusing on the user experience. User stories are mainly concerned about the who, what, and why. On the other hand, pseudocode describe the what and how.

Concluding Remarks

Writing user stories is not difficult, but it's also easy to get them wrong. You should be fine as long as the user stories you write fulfill the following:

  • written from the perspective of a user
  • identify the user, the feature, and the benefit (or answer the "who, what, and why?")
  • have the characteristics of INVEST
  • not too restrictive in terms of implementation
  • have Acceptance Criteria and Definition of Done (DoD)

User stories are great for identifying user needs and increasing the business value of a product. However, user stories do not cover implementation details and are not substitutes for a requirements document.

A user story is the smallest, functional unit in the Agile/Scrum Product Backlog. Most modern software development teams will require you to use it, so it is definitely worth learning. And even as a solo developer, writing down user stories will help you build a project that has user value and prioritize which features you should implement first.

Try writing user stories before you build your next project, and see how it helps!

Resources/Recommended Reading:

Thank You Banner

DISCLAIMER:

This is a Starter Guide meant for introducing beginners to user stories. This guide only expresses my thoughts and opinions (based on my limited knowledge) and is in no way a substitute for actual references. If I ever make a mistake or if you disagree, I would appreciate corrections and discussions in the comments!

Other Media

Feel free to reach out to me in other media!

Rammina Logo

Twitter logo

Github logo

Discussion (13)

Collapse
jmcp profile image
James McPherson

I've been a software engineer for 25y, and the "user story" way of describing requests-for-enhancements drives me up the wall.

For example, perhaps you identify that a particular component of an application is performing poorly, and that this can be improved. Why why should you have to write this as

"As a user of applicationX, I want componentY to perform better"

rather than

"componentY performs poorly when {condition summary} is {true or false}"

What is relevant here is that some aspect of the product/application/utility performs poorly under certain conditions - and who you are is irrelevant to that.

Or perhaps you want to add a new feature?

"As a user of applicationX, I want there to be a componentY"

As you allude to in the discussion, this doesn't give any idea of what is really needed, why it is needed, or concerns that might go in to designing and engineering a good solution.

Here's a synopsis that I wrote (and delivered the code to make it happen):

$bugid fwflash should be generic and pluggable

which you can see at src.illumos.org/source/history/ill.... fwflash is the Solaris firmware flashing utility.

That synopsis doesn't depend on any particular person's existence or involvement and describes at a high level what is needed. The RFE text (sadly, no longer available after Oracle shut down OpenSolaris.org) explained that

1- the existing tool was tightly coupled to one specific brand of device
2- the existing tool was not extensible to any new devices - even those from the manufacturer in #1, and
3- by solving #1 and #2 we could greatly improve the customer experience for all the flashable devices that Sun made and sold.

I could, I suppose, have written

As a user, I want to be able to flash/upgrade the firmware on any device sold by Sun

(and added a modifier like "easily") - but what does that actually add to our understanding of what is needed? Nothing, in my opinion.

By all means, if a particular user's identity or attributes is relevant, mention that. In my experience that is very rarely the case so I am firmly of the opinion that "as a [..]" should be excised.

Collapse
rammina profile image
Rammina Author

You bring up a good point. Following the typical format of
As a(n) ... I want to ... so I can...
is not mandatory in Agile and Scrum anyway.

Following that template does not guarantee a quality user story either. And in some cases, it is way too limiting or "stiff" to use when describing a requirement or need. In those cases, it might be better to just not follow the typical format or one could just create a Product Backlog Item instead.

I tend to think of the template as "training wheels" for Agile/Scrum teams who are new to writing user stories. That said, User Stories do not necessarily have to be in this format, but it guides the story writer into expressing those three important questions.

Thank you for sharing your insights!

Collapse
aminmansuri profile image
hidden_dude

As I understand it a User Story is for future features.

If you're saying "component X performs poorly" isn't that a Bug rather than a "user story"?

Our general practice is to schedule issues. Some issues may be future features (that could be expressed as "user stories") or it could be bugs that we need to fix (that are best expressed in the direct "component X doesn't work").

Or am I missing somehting?

Collapse
rammina profile image
Rammina Author

Yeah, Product Backlog Items are different from user stories. Not all issues are featured related (also not user stories).

Collapse
billraymond profile image
Bill Raymond

As a change consultant, I help organizations through what I will refer to as "agile transformations." My experience in writing user stories like those proposed in this article is excellent for framing the requirement, putting yourself in the right frame of mind, and bringing consistency to the planning process.

How exactly you write the user story (or requirement) does not always have to follow the exact word-for-word writing that this article proposes. Keeping the who, what, why, value and definition as a mental template is super helpful.

For example, I recently had a senior person wanting to build a bunch of new reports. They were spending a lot of unbudgeted money to drive new potential customers to their trade show (they had too many existing customers and wanted to onboard more customers). They requested new reports, changes to how we manage all our customer data, and potentially purchasing some new software that could help track all of this.

Their requirements spread across multiple teams with different requests and a lack of a cohesive strategy. The leader was trying to make things happen because they were taking a significant risk and wanted to measure the value of this big new budget spend. However, how the requirements were communicated, it would have taken multiple teams many months to complete. We took this as a training opportunity.

After asking some questions and thinking through the process, we already had all the systems in place; they just didn't know it. We mocked up the request in the form of a few reports, and they said, "Yes! That is what I want!". We took a multi-month effort and brought it down to two dashboard reports with a few minor modifications to the marketing software we used. The entire request took two weeks to complete, with a few minor bug fixes the following two weeks.

We walked the executive through the user story, which looks something like this:

As the lead for our big trade event, I require metrics that prove our planned X, Y, and Z marketing efforts has increased the number of new potential customers over existing customers.

The title of the Jira ticket had a label like this:
"New vs. existing customer differential dashboards"

The ticket details included a copy/paste of the leader's original user story. However, the ticket had more detail, such as assumed systems impacted, databases to access, and teams likely impacted. That additional detail was maybe a page long so the team could understand how we translated the requirement into something useful for engineering and report writers.

By demonstrating how to think about the request and share our process through a simple user story format, the leader better understood how to communicate with these select teams. Now, that leader understands the process, writes down their requests in the style of a user story, and then meets with the product owner to work out the details and the value.

Collapse
rammina profile image
Rammina Author

Thank you for sharing your experiences!

I do agree that the format helps other people be on the same page with the team. It can also make it easier to communicate and understand a specific requirement for non-technical people.

Collapse
pikot101 profile image
Pikot101

Nice... can you add 3C?

Collapse
rammina profile image
Rammina Author

Oh, sure! Something like a "The 3 C’s (Card, Conversation, Confirmation) of User Stories" section.

Thank you for the suggestion!

Collapse
rammina profile image
Rammina Author

I added 3Cs of User Stories just now!

Collapse
darkwiiplayer profile image
DarkWiiPlayer

Not a huge fan of "user stories", since I tend not to work on the types of projects that benefit from that sort of approach, but very nice article nonetheless 😀

Collapse
rammina profile image
Rammina Author • Edited on

Thank you!
Would you mind sharing with me what qualifies as projects that do not benefit much from user stories?

Thing that come to mind are personal projects made for your own self, and projects that have a very limited userbase.

I'm actually really curious, because I can't find any results wherever I look and most content that I see just give users stories too much praise.

It would be nice to know more about case scenarios in which they don't really work well for a project.
The closest I've ever seen to what you're talking about is covered in this article.

Collapse
darkwiiplayer profile image
DarkWiiPlayer

Mostly smaller internal projects that are used almost exclusively by coworkers that would rather just call one of the developers directly than opening an issue somewhere.

There's simply less of a need to write down user stories when you can simply sit down with your users and brain-storm how to best solve their problems.

But the small personal projects are obviously another good example.

Most of the stuff I do in my free time isn't meant for end-users anyway though, so user-stories wouldn't make any sense there.

Thread Thread
rammina profile image
Rammina Author

Thank you for sharing your insight!

I guess as a solo freelance developer I didn't really think about those cases.
Building applications to be used by fellow developers or other technical coworkers in the same company may not necessarily need user stories.