eboyle's guide to writing user stories
Rules:
Thou shalt have a shared backlog with all engineers on your pod
Thou shalt have all stories, chores, and bugs related to a product initiative in a single backlog
Exception: Tech debt or tech-only projects may have a separate technical backlog
STORIES
What does a story look like?
Name
As a [persona] doing [x], I can [y]
Description
Give a bit of context of why this story is important to the persona. If this is a part of a large set of stories, reference where it fits into the larger picture
UX/UI
[link to invision]
embedded image when possible
Acceptance Criteria
1. When x is clicked, y happens
2. Edge case expected behavior
What belongs in Acceptance Criteria?
I mean. This isn’t gospel… but this is the law according to eboyle: Any action or interface element that needs to be present, conditionally present, or change through the course of the story should have at least one acceptance criteria. Basically if an engineer is going to have to know the answer in order to build it, it should probably be in there.
Let’s take a look at some examples:
EXAMPLE 1:
As a Creator viewing PRM, I can filter by charge status (because this helps me do x)
Description
We want to add a new drop-down filter! The filter's label should be "Charge status," and it should list the "friendly" charge status labels (paid, pending, refunded, declined, deleted, fraud, other).
UX/UI
[link to invision]
Acceptance Criteria
1. A new single-choice drop-down filter is present to the right of the existing filters
2. The default option is "All charge statuses"
3. When a charge status is selected, the list should refresh automatically
4. If "Reset" is clicked, the charge status filter should clear
EXAMPLE 2:
As a Creator viewing PRM, I can sort the list by pledge value (because this helps me do x)
Description
By default, the list of Patrons is sorted in alphabetical order. We want to add the option to filter by a few other columns as well. In this story, we'll let creators sort by the current pledge value of patrons.
UX/UI
[link to invision]
Acceptance Criteria
1. When a creator mouses over the "Pledge" column header, the cursor becomes the hand (shows it's clickable)
2. When a creator clicks on the "Pledge" column header, and no previous sort was set on Pledge, the list is sorted by pledge value ascending
3. When a creator clicks on the "Pledge" column header, and the list was already sorted by Pledge asc, the list becomes sorted by pledge value desc
4. When a creator clicks on the "Pledge" column header, and the list was already sorted by Pledge desc, the list becomes sorted by pledge value asc
5. When the list is being sorted by Pledge asc, an upward arrow is displayed to the right of the column header
6. When the list is being sorted by Pledge desc, a downward arrow is displayed to the right of the column header
7. When the list is no longer sorted by Pledge, the arrow is removed
8. Upon sort, you go back to page 1
What does an API story look like?
Pretty similar, but with a few tweaks tailored to the real need. If you don’t feel comfortable writing this as a PM, that’s cool - partner with your Scrum Conductor!
Name
As an API Consumer, I can [x]
Description
Give a bit of context of why this story is important to the persona. If this is a part of a large set of stories, reference where it fits into the larger picture
Permissions
Who should have access to this endpoint? Just the creator? Patrons and creators? Patron only?
Inputs
What parameters should this endpoint accept? An ID? an array of IDs? Which of the inputs are required? Will you allow any side loading?
Outputs
What data should be returned when this endpoint is hit?
Acceptance Criteria
1.
EPICS
What’s an epic
Text book definition:
(https://www.atlassian.com/agile/delivery-vehicles)
An epic is a large body of work that can be broken down into a number of smaller stories. For example, performance-related work in a release. An epic can span more than one project, if multiple projects are included in the board to which the epic belongs.
Erin’s definition:
A way for a PM to keep their stories organized so as to stay relatively sane. Usually they align to some chunk of work that delivers value to a customer. I always prioritize within the epics, rather than try to prioritize the whole damned backlog. It’s just too much.
Do I have to use epics?
Absolutely not. If you’re working with only 2-3 engineers and you really only have a small scope of work, there’s no need for epics. Epics are more useful with larger teams who are working on multiple projects at once.
BREAKING IT DOWN
User stories should be granular enough that an engineer can complete the story within a day, generally speaking. Each team probably has their own point system, and each team should also have a threshold for pointing a story. Above that threshold, and you’ll need to split the story apart.
Most full-stack features will likely need some backend stories (database schemas, etc), some API stories (CRUD endpoints, for example), and frontend stories. Generally speaking, it’s great to keep these things separate.
Backend Stories
I’ll sometimes stub out the real technical work here (like creating a schema, etc), but mostly… I leave this up to the backend engineers to write.
API Stories
I like to write these out after getting a better understanding of what’s needed from the front end. What information will the page or state of your page need to be provided? In the case of a table or list feature, this comes in the form of which columns I need to display, or what information I need to be able to create or modify within the table.
Frontend Stories
To me, these are the easiest stories to break down (because I’m a visual person). I like to start with the largest, and least specific detail possible, and work my way down to various elements on a page.
For a typical “list” or “table” feature, I’d usually break it down like this:
The page exists, with the title
Data is displaying in an unformatted table (and here are the columns)
Data is displaying in a formatted table
Pagination controls are present
Hovering over a row does x
Button y is present, and when clicked does z
ESTIMATING
Are you an engineer? Great. You should be estimating. Are you a PM? Stop. Go get an engineer.
How should you estimate?
It’s cool for all engineering teams to do pointing in a slightly different way. However, there are definitely some best practices in how to think about estimates. Estimates should not reflect the amount of time it will take you to complete a task, but rather the relatively complexity of one task as compared to another. Fibonacci, as it turns out, is great for this.
Let’s say we have the following 5 stories in the backlog:
Change the description on Page x
Create a new modal that contains a list of data
Add a button on Page x that pops a modal
Create a new component to manage sorting for a table
A string change is probably… 1 point. If even. Is creating a new modal that hits and endpoint and displays data more or less complex than the string change? Sounds more complex. Great. Now, when you thinking about adding the button in comparison to the modal, is it less complex, or more complex? Probably a little less. And finally, how does the complexity of a new sort component compare?
At the end, you might say that the tasks, in order from least complex to most complex, are task 1, task 3, task 2, task 4.
To assign actual points, though, you have to go a step further. Is a button TWICE as complex as a string? Then 2 points is fine. Is it actually more than twice as complex? Maybe 3 points is a better estimate. The other thing to keep in mind is unknowns. The less certain you are about what it will take to fulfill any given task, the higher the point value you should give it.
After some time, the team should coalesce around roughly what points makes sense for your team, and have anecdotes like, “well a 3 point story feels like x, but a 5 point story feels like y.”
Why should you estimate?
A couple reasons. First, it should help you understand how much you might be able to accomplish in a week.
As engineers, estimates will inform how you think about milestones over time. At some point, you’ll have to say, “we think we might be done with x chunk of work by z date.” Understanding (over time) your point-based velocity will give you a more accurate prediction of this.
As a PM, estimates will help you understand the relative complexity of what may seem like small features, giving you the ability to prioritize more effectively. Is this 5 point story actually providing much more value than this other 2 point story? If not, maybe it’s time to scrap or de-prioritize that 5-pointer.
What even is an estimate?
It’s just that, an estimate. It is not a deadline, it is not a promise or guarantee, and it will often be wrong. It should also more often be directionally correct, and help us get better at things like milestones over time, because it’s a way for us to start quantifying and grasping something that is largely, let’s face it, unknown.
How much time will it take you to solve this puzzle?
Really hard question to answer, if you’ve never solved the puzzle.
How much time will it take you to solve this puzzle, given that it took you x minutes to solve this other puzzle that was similarly complex?
Easier to answer. But still very inexact.
Also, keep in mind that as a product organization we are AGILE. That means our priorities might change, or we might learn something new, or some unexpected thing will come up that will throw our milestone dates RIGHT out the window, even if we because wicked good at estimating with Fibonacci points to begin with.
tl;dr estimates are a tool, and nothing more
BACKLOGS
How much backlog is the right amount?
In general, the hand wavey rule on this (no, not just my rule, it’s a real thing) is about 2 weeks. In other words, you should always have 2 weeks of granular, fleshed-out stories for your team.
Can I have more?
I mean, of course. But, I’d encourage you to leave stories that won’t be addressed for >2 weeks at a higher level, like an epic.
What about all the ideas I don’t want to lose track of?
First of all, skeptical face. Second of all, keep an ideas backlog in some other place for you, as a PM, personally.
Also, I break these rules all the time, and should probably go blow really old stories away, because real talk we’re never going to get to them. And if/when we do we won’t remember there’s already a story.
