16 KiB
16 KiB
User Story Examples & Best Practices
A comprehensive guide to writing effective user stories with real-world examples across different domains.
Table of Contents
- User Story Format
- Anatomy of Good User Stories
- Examples by Domain
- Acceptance Criteria Patterns
- Common Mistakes
- Story Splitting
User Story Format
Standard Template
As a [user type/persona],
I want to [perform action/use feature],
So that [achieve benefit/value].
Alternative Formats
Job Story (Jobs-to-be-Done):
When [situation],
I want to [motivation],
So I can [expected outcome].
Feature-Driven:
In order to [receive benefit],
As a [user type],
I want [feature/capability].
Anatomy of Good User Stories
INVEST Criteria
Good user stories are:
- Independent: Can be developed and delivered separately
- Negotiable: Details can be discussed and adjusted
- Valuable: Delivers clear value to users or business
- Estimable: Can be sized/estimated by the team
- Small: Can be completed in one iteration/sprint
- Testable: Has clear acceptance criteria
Key Components
- User Type: Who is the user? Be specific.
- Action: What do they want to do? One clear action.
- Value: Why do they want it? The benefit or outcome.
- Acceptance Criteria: How do we know it's done? Testable conditions.
Examples by Domain
E-Commerce
Example 1: Product Search
User Story:
As a online shopper,
I want to filter products by price range,
So that I can find items within my budget.
Acceptance Criteria:
- Given I'm on the product listing page, when I set a minimum and maximum price, then only products within that range are displayed
- Given I've applied a price filter, when I clear the filter, then all products are shown again
- Given I set an invalid price range (min > max), when I apply the filter, then I see an error message
- Price filter persists when I navigate between pages of results
- Filter displays count of products matching the criteria
Priority: Must Have (P0) Story Points: 5
Example 2: Guest Checkout
User Story:
As a first-time customer,
I want to checkout without creating an account,
So that I can complete my purchase quickly.
Acceptance Criteria:
- Given I have items in cart, when I click checkout, then I see options for "Guest Checkout" and "Sign In"
- Given I choose guest checkout, when I enter shipping and payment info, then I can complete the order
- Given I complete a guest checkout, when the order is placed, then I receive a confirmation email
- After guest checkout, I see an option to create an account with my order information
- Guest checkout flow takes no more than 3 screens
Priority: Must Have (P0) Story Points: 8
SaaS / B2B Platform
Example 3: Team Collaboration
User Story:
As a project manager,
I want to assign tasks to team members,
So that everyone knows their responsibilities.
Acceptance Criteria:
- Given I'm viewing a task, when I click "Assign", then I see a list of team members
- Given I select a team member, when I confirm the assignment, then they receive a notification
- Given a task is assigned, when I view the task list, then I can see who is assigned to each task
- Given I'm a team member, when I'm assigned a task, then it appears in my "My Tasks" view
- I can assign multiple people to a single task
- I can change or remove task assignments
Priority: Must Have (P0) Story Points: 5
Example 4: Usage Analytics
User Story:
As a SaaS administrator,
I want to view team usage analytics,
So that I can optimize our subscription plan.
Acceptance Criteria:
- Given I have admin permissions, when I navigate to analytics, then I see usage metrics for the last 30 days
- Dashboard shows: active users, feature usage, API calls, and storage used
- Given I select a date range, when I apply the filter, then metrics update accordingly
- I can export analytics data as CSV
- Metrics update in real-time (max 5-minute delay)
Priority: Should Have (P1) Story Points: 8
Mobile App
Example 5: Push Notifications
User Story:
As a mobile app user,
I want to customize which notifications I receive,
So that I only see relevant updates.
Acceptance Criteria:
- Given I'm in settings, when I navigate to notifications, then I see toggle switches for each notification type
- Notification types include: messages, mentions, updates, promotions
- Given I disable a notification type, when that event occurs, then I don't receive a push notification
- Settings sync across devices using the same account
- Default settings are: messages ON, mentions ON, updates ON, promotions OFF
Priority: Must Have (P0) Story Points: 5
Example 6: Offline Mode
User Story:
As a mobile user with unreliable connectivity,
I want to access my recently viewed content offline,
So that I can continue using the app without internet.
Acceptance Criteria:
- Given I've viewed content while online, when I go offline, then I can still access the last 50 items viewed
- Given I'm offline, when I try to access new content, then I see a "No connection" message with cached content
- Given I'm offline and make changes, when I reconnect, then changes sync automatically
- Offline indicator appears in the app when connectivity is lost
- Cached content is automatically cleared after 7 days
Priority: Should Have (P1) Story Points: 13
Authentication & Security
Example 7: Two-Factor Authentication
User Story:
As a security-conscious user,
I want to enable two-factor authentication,
So that my account is protected from unauthorized access.
Acceptance Criteria:
- Given I'm in security settings, when I enable 2FA, then I can choose between SMS and authenticator app
- Given I choose authenticator app, when I scan the QR code, then I must enter a verification code to activate
- Given 2FA is enabled, when I log in, then I'm prompted for my second factor
- I receive backup codes when activating 2FA
- I can disable 2FA with my current password + 2FA code
Priority: Must Have (P0) Story Points: 13
Example 8: Password Reset
User Story:
As a user who forgot my password,
I want to reset it via email,
So that I can regain access to my account.
Acceptance Criteria:
- Given I click "Forgot Password", when I enter my email, then I receive a reset link within 5 minutes
- Reset link expires after 24 hours
- Given I click the reset link, when I enter a new password, then it must meet password requirements (shown on screen)
- After successful reset, I'm logged in automatically
- If email doesn't exist in system, show generic message (don't reveal if account exists)
Priority: Must Have (P0) Story Points: 5
Content & Media
Example 9: Video Upload
User Story:
As a content creator,
I want to upload videos with progress tracking,
So that I know when my upload is complete.
Acceptance Criteria:
- Given I select a video file, when I click upload, then I see a progress bar showing percentage complete
- Supported formats: MP4, MOV, AVI (max 2GB)
- Given upload is in progress, when I navigate away, then upload continues in background
- Given upload completes, when processing is done, then I receive a notification
- Given upload fails, when error occurs, then I see specific error message and can retry
Priority: Must Have (P0) Story Points: 8
Admin & Configuration
Example 10: User Permissions
User Story:
As an administrator,
I want to assign role-based permissions to users,
So that team members have appropriate access levels.
Acceptance Criteria:
- Given I'm viewing a user profile, when I click "Change Role", then I see available roles: Admin, Editor, Viewer
- Given I assign a role, when I save, then user immediately gains/loses associated permissions
- Admin: full access; Editor: create/edit content; Viewer: read-only
- I can create custom roles with specific permission combinations
- Audit log records all permission changes with timestamp and admin who made the change
Priority: Must Have (P0) Story Points: 13
Acceptance Criteria Patterns
Given-When-Then Format
Most structured format, excellent for complex logic:
Given [initial context/state],
When [action/event],
Then [expected outcome].
Example:
Given I'm a logged-in user with items in my cart,
When I apply a 20% discount code,
Then the cart total is reduced by 20% and displays the discount.
Checklist Format
Simpler, good for straightforward requirements:
- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Edge case handling
Table Format
Great for multiple scenarios:
| Condition | Action | Expected Result |
|---|---|---|
| Valid email | Click "Send" | Confirmation message |
| Invalid email | Click "Send" | Error message |
| Empty field | Click "Send" | "Required field" error |
Common Mistakes to Avoid
❌ Too Technical
Bad:
As a user,
I want the system to use Redis caching with 10-minute TTL,
So that page loads are fast.
Good:
As a user,
I want pages to load in under 2 seconds,
So that I can browse efficiently.
Why: User stories focus on user value, not implementation. Let engineers choose the solution.
❌ Too Vague
Bad:
As a user,
I want the app to be fast,
So that I have a good experience.
Good:
As a user,
I want search results to appear in under 1 second,
So that I can quickly find what I need.
Why: "Fast" is subjective. Be specific and measurable.
❌ Missing the "Why"
Bad:
As a user,
I want to upload profile pictures.
Good:
As a user,
I want to upload a profile picture,
So that other users can recognize me in the community.
Why: Understanding the "why" helps the team make better decisions.
❌ Multiple Actions in One Story
Bad:
As a user,
I want to create an account, set up my profile, and invite team members,
So that I can start using the platform.
Good: Split into three stories:
Story 1: As a user, I want to create an account...
Story 2: As a user, I want to set up my profile...
Story 3: As an account owner, I want to invite team members...
Why: Stories should be small and focused on one capability.
❌ No Acceptance Criteria
Bad:
As a user,
I want to search for products,
So that I can find what I need.
Good: Add specific criteria:
Acceptance Criteria:
- [ ] Search works on product name and description
- [ ] Results display in under 2 seconds
- [ ] Displays "No results found" when no matches
- [ ] Shows top 20 results with pagination
Why: Acceptance criteria define "done" and enable testing.
Story Splitting Techniques
When a story is too large, use these techniques to split it:
1. By Workflow Steps
Large Story:
As a user, I want to book a flight online.
Split Stories:
- Search for flights
- Select flight
- Enter passenger details
- Choose seat
- Make payment
- Receive confirmation
2. By User Persona
Large Story:
As a user, I want to manage my subscriptions.
Split Stories:
- As a free user, I want to view available plans
- As a paid user, I want to upgrade my plan
- As an admin, I want to manage team subscriptions
3. By Business Rules
Large Story:
As a user, I want to apply discount codes.
Split Stories:
- Apply percentage discount (e.g., 20% off)
- Apply fixed amount discount (e.g., $10 off)
- Apply free shipping discount
- Handle expired discount codes
- Limit one discount per order
4. By Data Variations
Large Story:
As a user, I want to import contacts.
Split Stories:
- Import from CSV file
- Import from Google Contacts
- Import from Microsoft Outlook
- Import from LinkedIn
5. By CRUD Operations
Large Story:
As a user, I want to manage my projects.
Split Stories:
- Create a new project
- View project details
- Update project settings
- Delete a project
6. By Happy Path / Edge Cases
MVP Story (Happy Path):
As a user, I want to upload a profile photo (JPG, < 5MB).
Follow-up Stories:
- Support additional formats (PNG, GIF)
- Handle files larger than 5MB with error message
- Auto-crop/resize images
- Allow photo deletion
Story Sizing Guidelines
Story Points Reference
1-2 Points (Few hours):
- Simple UI change
- Copy update
- Minor configuration
3-5 Points (1-2 days):
- New form with validation
- Simple API endpoint
- Basic feature toggle
8 Points (3-5 days):
- Complex form with business logic
- Integration with third-party service
- New database schema with migration
13+ Points (1+ weeks):
- Too large! Split the story
- Consider as an Epic
Templates for Common Scenarios
Registration/Sign-Up
As a new visitor,
I want to create an account with my email,
So that I can access personalized features.
Acceptance Criteria:
- [ ] Email and password required (password: min 8 chars, 1 number, 1 special char)
- [ ] Email validation and duplicate check
- [ ] Confirmation email sent upon registration
- [ ] Automatically logged in after email confirmation
- [ ] Option to sign up with Google/Apple (social auth)
Data Export
As a user,
I want to export my data as CSV,
So that I can analyze it in Excel.
Acceptance Criteria:
- [ ] Export button in settings
- [ ] Includes all user data (specify fields)
- [ ] File downloads immediately (or email if > 10MB)
- [ ] Filename format: "export_[username]_[date].csv"
- [ ] Respects data privacy regulations (only user's own data)
Error Handling
As a user,
I want to see helpful error messages,
So that I know how to fix issues.
Acceptance Criteria:
- [ ] Error messages are specific (not generic "Error occurred")
- [ ] Suggest actionable next steps
- [ ] Display in user's language
- [ ] Don't expose technical details (stack traces)
- [ ] Log errors for debugging (backend)
Best Practices Summary
- Write from user perspective, not system perspective
- Focus on value/benefit, not just functionality
- Keep stories small (completable in one sprint)
- Make acceptance criteria testable
- Use consistent format across your team
- Include edge cases in acceptance criteria
- Collaborate with engineers and designers when writing
- Refine regularly based on new learnings
- Link to mockups/designs when relevant
- Prioritize ruthlessly (must/should/nice-to-have)
Additional Resources
User Story Template
Title: [Concise feature name]
As a [specific user type],
I want to [action/capability],
So that [benefit/value].
Acceptance Criteria:
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Edge case handling]
Priority: [Must Have / Should Have / Nice to Have]
Story Points: [1/2/3/5/8/13]
Dependencies: [List if any]
Design: [Link to mockups]
Notes: [Additional context]
Epic vs Story vs Task
Epic: Large body of work (multiple sprints)
- Example: "User Authentication System"
Story: Deliverable value (one sprint)
- Example: "As a user, I want to reset my password..."
Task: Implementation step (hours/days)
- Example: "Create password reset API endpoint"
Conclusion
Effective user stories:
- Start with the user's perspective
- Clearly articulate value
- Include testable acceptance criteria
- Are sized appropriately
- Enable team collaboration
Use these examples as templates, but adapt them to your product and users' specific needs!