A user story is a concise description of a software feature from an end user's perspective, narrated using non-technical language. It typically follows the format: "As a **persona**, I want to **software goal**, so that **result**". The term "end user" can refer to external customers or internal stakeholders benefiting from the feature.

Writing Effective User Stories

Understand the target audience's demographics and psychographics to define the user persona accurately. Design the feature to address their needs and help them achieve their goals, focusing on user intent rather than technical details. Also

Adhere to INVEST Criteria

An effective user story should adhere to the INVEST criteria to ensure clarity, feasibility, and value delivery: **Independent:** User stories should be self-contained and independent, to enable developemnt and delivery without reliance on other stories. **Valuable:** Each user story should deliver tangible value to the end user or stakeholder, by enhancing functionality, user experience, or productivity. **Estimable:** User stories should be sufficiently detailed to allow for estimation of effort and duration required for implementation **Small:** User stories should be broken down into small, manageable chunks of work that can be completed within a single sprint. **Negotiable:** User stories should be open to negotiation and refinement throughout the development process to accommodate evolving requirements. **Testable:** More on this later. **Prioritized:** More on this later.

Fixing Common Mistakes in User Stories

**Use Consistent Language:** Establish a glossary early in the project to define terms consistently and ensure clarity across all stakeholders **Focus on User Goals:** Understand the underlying user intent behind each story. Consult real users or representatives to refine requirements accurately. **Remove Technical Details If not needed:** Separate user goals from implementation specifics to maintain relevance and flexibility. Should the user get notified by Kafka or a webhook? Does it really matter? The user just wants to get notified, using either technology won't matter, in the end. But will it matter for the user if they receive the notification through email or other means? Yes. **Clarifying Roles:** Yes, it's called User Story but, not everyone is a user. Tailor user stories to specific user roles (e.g., manager, admin, architect, group leader?) to ensure features meet diverse user needs.

Good and Bad User Story Examples

You might find these ones in the wild

Bad Examples

**#1:** As a user, I want a button on the homepage. - **\> Problem:** This user story lacks context, purpose, and specific user intent. **#2:** As a developer, I want to refactor the codebase. - **\> Problem:** Focuses solely on the developer's task, missing value or outcome. **#3:** As a manager, I want reports. - **\> Problem:** Doesn't specify the purpose or value of the reports for the user. These reports can literally be about anything. **#1:** As a first time website visitor, I want the landing page to be fast. - **\> Problem:** Vague and lacks clarity on the specific performance improvement needed. How can "fast" be tested? Is there a concrete metric? Is it fast on a Mac? Or an old android? How many milliseconds should it take to be considered "fast"?

Good Examples

**#1:** As a registered user, I want to reset my password via email verification if forgot it, so that I can regain access to my account. - **\> Persona:** Registered User. - **\> Needs:** Password reset functionality. - **\> Purpose:** Account security and user autonomy. **#1:** As a customer, I want to receive email notifications for order updates, so that I can track the status of my purchases conveniently. - **\> Persona:** Customer. - **\> Needs:** Order status update. - **\> Purpose:** Enhanced customer experience and order management. **#1:** As a project manager, I want a web dashboard displaying real-time project milestones and tickets completion, so that I can monitor project progress to make informed decisions. - **\> Persona:** Project Manager - **\> Needs:** Real-time project metrics - **\> Purpose:** Improved project visibility and decision-making

Testability

Rewrite user stories using Behavior-Driven Development (BDD) format, such as Gherkin syntax, so you can directly map these stories to executable tests, and ensure that the software meets the specified requirements and behaviors.

Gherkin Syntax

This is how to write user stories in Gherkin syntax

Example 1: Password Reset Feature

*"As a registered user, I want to reset my password via email verification, so that I can regain access to my account securely."* Can be written as





You see how better it gets? Here's another one

Example 2: Order Status Notifications

*"As a customer, I want to receive email notifications for order updates, so that I can track the status of my purchases conveniently."* Can be written as




Ranking

Did I mention that, when a user story is set, it needs a priority level. The method you use might differ, in my projects I use the MoSCoW method.

Unclassified, raw

User Stories