User Story – writing guidelines and checklists
In this week’s technical writing tutorial, we look at how to write a user story. You can use these guidelines and checklists to refine your user stories, expand the material to help your readers understand the scenario, allow developers to code the requirement, and testers to ensure it meets the acceptance criteria. Let’s get started.
How can I improve my user stories?
As a product manager, improving user stories is crucial to the success of your product.
Here are some guidelines to follows:
- User focus: User stories should always start with the user, and their needs or pain points should be the focal point of the story. Frame the user story to convey who the user is, what they want to achieve, and why it matters to them.
- Concise: Be brief and to the point. Avoid adding unnecessary details and keep the focus on what the user wants to achieve.
- Plain language: Avoid technical jargon or complex language that might confuse the user. Use plain and simple language that is easy to understand.
- Actionable: A good user story should be actionable, meaning it should clearly articulate what the user wants to do, and what action they need to take to achieve their goal.
- Acceptance criteria: Define clear acceptance criteria that will be used to determine whether the user story has been successfully implemented. These criteria should be specific, measurable, and actionable.
- Prioritize user stories: identify their importance to the user and their business. This helps focus on the most critical features and ensure that they are developed first.
- Get feedback: Get feedback from stakeholders, developers, and users to ensure that the user stories are clear, actionable, and aligned with the product vision. This will help you refine the user stories and improve the overall product.
User Guide Writing – Good and Bad Examples
Give me some good and bad examples!
Ok, so, for each of the above, I’ve prepared more detailed examples:
Focus on the user:
Bad: “As a website user, I need a button to sign up for the newsletter.”
Good: “As a website user who is interested in receiving updates and promotions from the company, I want to easily subscribe to the newsletter so I can stay informed about new products and special offers.”
Keep it concise:
Bad: “As a user of the shopping cart, I need to be able to add items to my cart, view my cart, and remove items from my cart, so that I can complete my shopping experience without any obstacles.”
Good: “As a shopper, I want to easily add, view, and remove items from my cart so that I can quickly and seamlessly complete my purchase.”
Use plain language:
Bad: “As a user, I require a UX that is consistent and intuitive across all channels.”
Good: “As a user, I want a user experience that is easy to use and looks and feels the same across all devices and platforms.”
Make it actionable:
Bad: “As a user, I want better search results.”
Good: “As a user, I want to easily find what I’m looking for in the search results so that I can quickly complete my task.”
Include acceptance criteria:
Bad: “As a user, I want a login screen that is easy to use.”
Good: “As a user, I want a login screen that includes both email and password fields, and allows me to reset my password if I forget it.”
Prioritize user stories:
Bad: “As a user, I want to be able to change the color of the text on my profile page.”
Good: “As a user, I want to be able to see my profile information and edit it easily so that I can keep my information up to date.”
Get feedback:
Bad: “As a user, I want a navigation bar that is easy to use.”
Good: “As a user, I want a navigation bar that includes clear labels and is easy to use so that I can quickly find what I’m looking for.”
Get the idea?
User Stories for E-commerce website
Let’s look at how these might apply to a fictitious e-commerce website:
Focus on the user:
As a busy parent who shops online frequently, I want to be able to quickly reorder items from my past orders so that I can save time and easily restock my pantry.
As a fashion-conscious millennial who likes to keep up with the latest trends, I want to be able to filter search results by color, size, and price range so that I can find the perfect outfit for any occasion.
Keep it concise:
As a shopper, I want to be able to easily view my order history and track my packages so that I can stay up-to-date on my deliveries.
As a user, I want to be able to easily browse and compare products across different categories so that I can make an informed purchasing decision.
Use plain language:
As a first-time user of the website, I want to be able to easily find the customer support section so that I can get help with any questions or issues I have.
As a frequent user of the website, I want to be able to easily add items to my cart, view my cart, and checkout so that I can complete my purchases quickly and efficiently.
Make it actionable:
As a user, I want to be able to easily leave product reviews and ratings so that I can help other shoppers make informed purchasing decisions.
As a user, I want to be able to easily filter search results by product rating and customer reviews so that I can quickly find the best products.
Include acceptance criteria:
As a user, I want the checkout process to be quick and secure, and I expect to receive a confirmation email with my order details and estimated delivery date.
As a user, I want the product pages to include high-quality images, detailed product descriptions, and accurate pricing information.
Prioritize user stories:
As a user, I want to be able to easily view and manage my account information, including my shipping and billing addresses and payment methods.
As a user, I want to be able to easily contact customer support via phone, email, or live chat for any issues or questions I may have.
Get feedback:
As a user, I want the website to be easy to navigate and visually appealing, and I expect to receive prompt and helpful customer support if I encounter any issues.
As a user, I want the website to offer a wide selection of high-quality products at competitive prices, and I expect to be able to quickly and easily find what I’m looking for.
Common mistakes when writing user stories
Here are some common mistakes product managers make when writing user stories:
- Focusing on features instead of user needs: Product managers sometimes write user stories that focus on specific features or functions, rather than on the underlying user needs. This can lead to products that are not well-aligned with user needs and do not provide a good user experience.
- Writing vague or unclear user stories: If user stories are not specific and actionable, they can be difficult to understand and may not provide clear direction for development teams. This can lead to misunderstandings and delays in product development.
- Overcomplicating user stories: User stories should be concise and easy to understand. Product managers sometimes overcomplicate user stories by including too many details or requirements, which can make it difficult for developers to focus on the most important features.
- Failing to prioritize user stories: Not all user stories are equally important. Product managers sometimes fail to prioritize user stories, which can lead to delays and confusion in development.
- Ignoring feedback from users and stakeholders: User stories should be informed by feedback from users and stakeholders. Product managers sometimes fail to seek out and incorporate feedback, which can lead to products that do not meet user needs or fail to gain traction in the market.
- Neglecting to include acceptance criteria: Acceptance criteria are the conditions that must be met for a user story to be considered complete. Product managers sometimes neglect to include acceptance criteria, which can lead to confusion and uncertainty about what is expected from the development team.
- Failing to update user stories: User stories should be updated throughout the development process as new information becomes available. Product managers sometimes fail to update user stories, which can lead to misunderstandings and delays in development.
What’s the difference between user story and use case
A user story and a use case are both techniques used in software development to capture user requirements and describe the behavior of a system. However, there are some key differences between them:
- Scope: A user story typically describes a single feature or piece of functionality from the perspective of the user. It is focused on a specific user need and the value that the feature will provide to the user. In contrast, a use case describes a complete sequence of actions and interactions between the user and the system to achieve a specific goal or objective. It covers a broader scope than a user story and includes all the possible scenarios and outcomes related to the user’s goal.
- Level of detail: A user story is often a short, simple statement that provides a high-level description of a feature or functionality. It is intentionally kept vague and open-ended to encourage collaboration and discussion between the development team and the stakeholders. In contrast, a use case is a more detailed description of the system’s behavior that includes a flow of events, inputs and outputs, and pre- and post-conditions for each step of the process.
- Format: A user story is typically written in a specific format that includes the user role, goal, and benefit, such as “As a [user role], I want to [goal] so that [benefit].” In contrast, a use case is typically written in a more structured format that includes a use case name, actors, trigger, preconditions, flow of events, alternative flows, and post-conditions.
- Flexibility: A user story is meant to be flexible and adaptable to changes in requirements or priorities. It is often refined and elaborated over time as the development team gains a better understanding of the user’s needs. In contrast, a use case is usually more rigid and less adaptable to changes in requirements or priorities.
User stories and use cases serve different purposes and have different levels of detail and scope. While a user story is a high-level description of a feature or functionality from the user’s perspective, a use case is a more detailed description of a specific sequence of events and interactions between the user and the system.
What to include in a user story template?
In general, your user story template should include the following elements:
- Role: This identifies the user or persona for whom the story is written. It should describe the user’s role or job title in the context of the product or system.
- Goal: This describes what the user wants to accomplish or achieve. It should be specific, measurable, and achievable.
- Benefit: This explains why the user wants to accomplish this goal. It should describe the value that the user will gain from achieving the goal.
- Acceptance criteria: This specifies the conditions that must be met for the user story to be considered complete. It should be written in a way that is measurable and verifiable. Acceptance criteria help the development team understand when the user story is done and ensure that it meets the user’s expectations.
- Priority: This indicates the importance or urgency of the user story relative to other user stories. Priority helps the development team know which user stories to work on first and ensures that the most important features are developed first.
- Complexity: This indicates the level of effort required to implement the user story. It helps the development team estimate how long it will take to complete the user story and plan their work accordingly.
A typical user story template might look like this:
“As a [role], I want to [goal] so that [benefit]. Acceptance criteria:
[Condition 1] [Condition 2] [Condition 3] Priority: [High/Medium/Low] Complexity: [Small/Medium/Large]”Note that the exact format and wording of a user story template may vary depending on the needs of the development team and the organization.
Recommendations
Here are some recommendations for writing effective user stories:
- Focus on the user: User stories should be written from the perspective of the user and should focus on their needs and goals. Avoid writing stories from the perspective of the system or the development team.
- Keep them simple: User stories should be simple and easy to understand. Avoid using technical jargon or complex language. Use plain language that is accessible to all stakeholders.
- Use real-world examples: Use real-world examples and scenarios to help make the user story more concrete and relatable. This can help stakeholders better understand the user’s needs and ensure that the story is focused on a specific, real-world use case.
- Use the INVEST criteria: Use the INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) to evaluate and refine your user stories. INVEST helps ensure that user stories are well-defined and can be implemented effectively by the development team.
- Collaborate with stakeholders: Involve stakeholders in the process of writing and refining user stories. This can help ensure that the stories are aligned with their needs and expectations and can improve the overall quality of the product.
- Prioritize ruthlessly: Prioritize user stories ruthlessly based on their business value and user impact. This can help ensure that the development team is focused on delivering the most important features first and can help maximize the return on investment for the product.
- Keep them up-to-date: User stories should be living documents that are updated and refined over time as the development team gains a better understanding of the user’s needs and the product evolves. Regularly review and update user stories to ensure they remain relevant and accurate.
Next week, we look at how to write work instructions.