Skip to content

Commit

Permalink
Update how_we_write_user_stories.md
Browse files Browse the repository at this point in the history 
Replaced content with the content from confluence. https://labzero.atlassian.net/wiki/spaces/PDE/pages/1967259693/Epics+and+User+Stories
  • Loading branch information
@traceykthompson
traceykthompson authored Mar 11, 2024
1 parent 1eca698 commit 4774f26
Showing 1 changed file with 67 additions and 83 deletions.
150 changes: 67 additions & 83 deletions product_design/how_we_write_user_stories.md
View file
Original file line number Diff line number Diff line change
@@ -1,105 +1,89 @@
## Why write user stories?
## Epics and User Stories

Lab Zero writes user stories to place a product’s users at the center of our thinking and decision-making. User stories also support our ability to validate product hypotheses, deliver value early, often and predictably, make better trade-offs, and prioritize effectively.
* Contents
{:toc}

**Stories generate interest, empathy and vision.** At the highest level, stories embody the things that make your product worth building — who it’s for and what they can do to achieve their goals. If your team isn’t aligned on these core goals, they won’t know how to prioritize their work to achieve the greatest outcomes for the least effort.
## The role of Epics and User Stories in our work

**Stories focus conversation.** A story allows the team to make multiple confirmations of the task throughout the development process. This begins with agreement on the task to be done, and later, how it will pass acceptance testing.
Epics and User Stories are tools that focus our conversation around what to build and why. At the highest level, they embody the things that make our product worth building — who it’s for and what that person can do with the product to achieve their goals.

## What is needed before we write user stories?
- Epics describe the vision and the outcomes we are striving to achieve and how we intend to measure success.
- User stories generate empathy and alignment around a discrete effort and how that work will benefit the user. Writing user stories helps us come to an agreement on what needs to be done and what criteria we will use to tell when the work is complete.

**Map the customer’s experience.** Armed with your customer research (you’ve defined personas based on qualitative and quantitative research, right?) put yourself in the customer’s shoes and map their journey as you understand it today.
This document describes the best practices we aspire to. Not every project will follow this approach exactly. We’ll rely on our team norming sessions to decide how to adapt this approach so that it best supports the team in the context of their project.

**Define a clear goal.** Review your map with the project’s stakeholders to confirm your current understanding and agree upon a single experience or interaction which matches a single business outcome. Clarify the riskiest assumption, define your hypothesis, and explain how you will test and measure success.
## Writing Epics and User Stories is a collaborative process
We believe writing Epics and User Stories is a collaborative process between the Product Manager, the Designer, and a Lead Engineer. In addition to the responsibilities described below, we highly encourage our teams to pair throughout the process.

**Draft a design.** Designs help clarify to the entire team what will be done. They naturally tease out edge cases. Discuss with your team what fidelity of design is right for your situation.
### The Product Manager is responsible for clear epics.
The Product Manager is responsible for defining the value the product should deliver based on our current understanding of the customer’s goals, the desired business outcomes, and priorities.

## Story Structure
### The Designer is responsible for the clear, actionable user stories… *unless it’s a technically-focused ticket.*
When we translate a design into tickets ready for engineering, the Designer is the person with the greatest knowledge of the user experience and what requirements need to be reflected in the ticket. That does not mean design must do this work alone. Product and Engineering feedback is valuable here and the Designer may consider scheduling time to pair to ensure tickets are clear.

**[User] --> [does or sees something] + [optional qualifiers] --> in order to [accomplish a clear goal].**
*The exception is when the user story does not have a design component.* In these cases, someone else is the expert. These types of tickets may be written by the Product Manager or the Lead Engineer with input from Design.

#### User…
### The Lead Engineer will always be consulted on epics and design-focused stories… *and is also responsible for clear, actionable technically-focused stories when needed.*
Without an engineering perspective, all our epics and stories are just wishes. Engineering provides a critical perspective into feasibility. They need to be kept in the loop so their team is aligned on the why behind our work. They should be consulted early and often. The Lead Engineer should have weighed in on context and design well before a ticket makes it to Backlog Prioritization.

Choose a personal or functional role within your system.
## Why do we approach Epics and User Stories this way?
Our approach enables
- the **Product Manager** to focus on the **“why,”**
- the **Designer** to focus on the **“what,”**
- the **Engineering team** to focus on the **“how,”**

#### …does or sees [something]” + [optional qualifiers]
While encouraging **conversation and collaboration** along the way.

Be concrete but not overly verbose - let the design fill in the details.
## Our Approach: From Epic to User Story to Sprint
The full kickoff-to-backlog process is outlined in the [Discovery Journey Map](https://www.figma.com/file/I8gn3uTpbA7dakZu7xdUjj/LZ-discovery-journey-map-%5BWIP%5D?node-id=0%3A1).

#### ...in order to [accomplish a goal].
The list below describes the best practices we aspire to. Not every project will follow this approach exactly. We’ll rely on our team norming sessions to decide how to adapt this approach so that it best supports the team in the context of their project.

Describe the outcome the user achieves.
1. **Draft speclet** <br>
The Product Manager begins by writing a speclet that will serve as a stand-in for the epic. High-level user stories focusing on user needs are added to this document as the Discovery progresses. <br>
2. **Begin design**<br>
When the Designer has enough context on the problem (from the speclet and discovery) they begin work on designs.<br>
3. **Create Epic in Jira** <br>
Product Manager creates the Epic(s) and possibly shell user story tickets in Jira.
Follow [this guidance](tbd) on epics.<br>
4. **Add User Stories to the Epic**<br>
When designs are agreed on, the Designer prepares the designs for handoff and [writes detailed user stories based on the designs](tbd). *If the epic doesn’t have a user interface, it may be more appropriate for the Lead Engineer to write the user stories.*<br>
5. **Preview stories**<br>
The Product Manager, Designer, and Lead Engineer review all stories before Storytime and estimation.<br>
6. **Initial prioritization**<br>
Product Manager prioritizes stories before Storytime so that we estimate the highest priority tickets first.<br>
7. **Storytime (estimation)**<br>
PM and Designer schedule a Storytime meeting with the sprint team.
- If the Designer wrote the story, they take the lead in talking through it.
- Stories are discussed and estimated by those involved in delivering the story.
- Stories may be broken down into smaller tickets if needed
- User stories must have an estimation before they are considered ready to be included in a sprint.<br>
8. **Final prioritization**<br>
PM reprioritizes the backlog before Sprint Planning and Kickoff. This helps ensure the highest priority tickets are ready for the next sprint and the backlog is prioritized with this new work. <br>
9. **Sprint Planning**<br>
Meeting where we align our commitments for the next sprint with our actual capacity.<br>

Further information on [Sprint Ceremonies can be found here](../project_kickoff/ceremonies.md).

## Acceptance Criteria
## Our responsibilities during the sprint
### Answering Questions
If questions come up during the sprint, the Designer is the first line to answer the question. They may pull the Product Manager and/or the Lead Engineer into the conversation if needed.

The description in your story should provide additional context and clarify what will be tested when the story is delivered.
### Accepting User Stories
On a pre-defined environment (for example, a Staging site), we verify that the work delivered meets the Acceptance Criteria before accepting the story.

Consider trying the “Given-When-Then” formula, a template intended to guide the writing of acceptance tests ([Gherkin](https://cucumber.io/docs/gherkin/)). It is likely that the developer will write automated tests based on your story, some tests may match the criteria you use to accept the work.
**Right person, right story, right time.** It is important to understand who on the team has the proper skills to accept the story at hand.
- Design or interaction-heavy stories should be accepted by a designer, preferably the individual who created the design.
- If you can’t verify an engineering task, don’t accept the story — find a developer who can.
- Do not allow delivered stories to sit for more than a day without acceptance testing. This can unnecessarily lengthen the feedback loop, reducing positive momentum and allowing the team to forget the specifics of the work.

* Given [some context, this is the pre-condition to the activity]
* When [some action is carried out]
* Then [a particular change or set of changes you expect due to the specified action]
**Reject early, reject often.** The Reject action is the flag to begin a conversation. You are not saying that the effort put forth has no value, just that the Acceptance Criteria have not yet been met.
- Comments must be added along with steps to reproduce any unmet criteria. Work out with your team the right amount of information to add when rejecting.
- Consider using software like [Licecap](https://www.cockos.com/licecap/) if an animated gif may help clarify the actions you have performed.

Here's an example of a login story.
>_Feature: As a user I want to sign in and see my orders_
>
>__Scenario: User supplies correct username and password__
>_Given that I am on the log in page_
>_When I enter my username and password correctly_
>_And click 'Sign in'_
>_Then I am taken to my dashboard showing my orders_
>
>__Scenario: User does NOT supply correct username and password__
>_Given that I am on the log in page_
>_When I enter my username and password incorrectly_
>_And click 'Sign in'_
>_Then I see an error message ‘Sorry, incorrect user name or password.”_
<br>
<br>

To clarify the standard for completion for all stories in the backlog, define your team’s technical “Definition of Done” in a visible place at the beginning a project. For example, at Lab Zero, completing a story requires not only implementing it and fulfilling the acceptance criteria, but also writing tests, running test suites and using pull requests to merge code.

## Who writes the stories?

Lab Zero likes to have the product owner write epics, and the designer write user stories.

Why?

It helps plant the product owner firmly in the problem space: defining the value the product should deliver based on our current understanding of the customer’s goals, the desired business outcomes and priorities.

This empowers the designer to work creatively on the customer experience moment-to-moment — the interaction patterns, design principles, edge cases.

We’ve seen a number of problems arise if user stories are written prior to or without the designer’s involvement:

* Design doesn’t have enough time to fully consider the customer experience. Instead, they’re forced to design based on a list of tactical stories possibly written from the business owner’s perspective, instead of the user’s.
* The pre-written stories don’t match the final design, and dev has to reconcile the inconsistencies before starting work.
* The stories are incomplete. It’s hard to anticipate all the edge cases of a feature before it’s gone through the design process.

## Story Time

Team partnership and peer review is essential to achieve strong alignment and buy-in.

**Early peer review:** After the designer has written stories, the product owner should review and provide feedback on the first draft. A second pair of eyes helps ensure focus and clarity of content. It also gives the product owner time to review the backlog as a whole to confirm that it represents the scope and priority of work.

**Full team review:** The designer presents each story in the backlog to the full team for feedback and estimation. Common results of an effective team review:

* Stories are sized
* Missed edge cases are exposed
* Hidden technical work is revealed (and added to the backlog)
* Stories are re-prioritized
* Proposed solutions are reconsidered and stories are decomposed/rewritten

**Prioritization:** Through team discussion, the team should have a good understanding of how they intend to deliver value in an incremental fashion. Now the product owner can take one more shot at the backlog to meet prioritized business & customer goals, produce a vertical slice, and/or reduce inter-story dependencies in the same sprint.

## Working on a user story

An effective user story stands on its own but is strengthened by the context you already know about the project. Whether you’re a designer working on an epic, or a developer working on an interaction story, do not work on a story that is unclear. Find time to clarify the task with the right person before moving forward.

Delivering: a story should be marked as delivered after it’s been merged to the proper environment and the test suite passes.

## Accepting user stories

You must be able to verify on a pre-defined environment that the work delivered meets the Acceptance Criteria before accepting the story.

**Right person, right story, right time.** It is important to understand who on the team has the proper skills to accept the story at hand. Design or interaction-heavy stories should be accepted by a designer, preferably the individual who created the design. If you can’t verify an engineering task, don’t accept the story — find a developer who can. Do not allow delivered stories to sit for more than a day without acceptance testing. This can unnecessarily lengthen the feedback loop, reducing positive momentum and allowing the team to forget the specifics of the work.

**Reject early, reject often.** The Reject action is the flag to begin a conversation. You are not saying that the effort put forth has no value, just that the Acceptance Criteria have not yet been met. Comments must be added along with steps to reproduce any unmet criteria. Work out with your team the right amount of information to add when rejecting. Consider using software like [Licecap](https://github.com/justinfrankel/licecap) if an animated gif may help clarify the actions you have performed.
## Related pages
- [Development Workflow](../continuous_delivery/development_workflow.md) guide
- [Definition of Ready and Done](https://labzero.com/blog/essential-working-agreements-ready-and-done) blog post

0 comments on commit 4774f26

Please sign in to comment.