Writing user stories is a task that sounds easy but really isn’t. A well-written story should be clear and concise and have enough information that a developer can get to work on it quickly. Over years of picking up different stories, I’ve recognized a few things about them that have made my job easier.
Separate the story into distinct sections.
A story that is a wall of text is hard to parse. That makes it difficult for a dev to figure out what it requires. Different teams may need different things, but a system that I’ve always liked includes three sections: Context, Technical Notes, and Acceptance Criteria.
The context describes the why. It gives background on why we’re writing the story and what problems it’s supposed to solve.
Technical notes can describe tools that may need to be used and considerations to take into account. Technical notes should not describe implementation details except in very specific circumstances. Some stories don’t need technical notes. In my experience, they’re commonly used in stories that are the result of a spike.
Acceptance criteria is the most important, regardless of your team’s preferences. Acceptance criteria should describe what must be done for the team to consider the story complete. There should be as little wiggle room as possible. Well-written acceptance criteria should list what the team must do and sometimes what doesn’t need to be done to protect against scope creep.
Avoid blocking stories with other stories when possible.
It is impossible to write every single story so it’s free of blockers, but it is possible to reduce them. Try to write stories that depend on as few other stories as possible. Identify potential dependencies while writing stories, and try to work around them. Minimizing blockers maximizes parallelization.
As an example, imagine an app where a user can request a list of resources from a service by clicking a button. Those resources then display on the screen. If the service doesn’t exist yet, the story is blocked. Instead, write two separate stories. One story for clicking a button that makes a request, and another story for displaying data on the screen.
Another consideration is to try to avoid writing “laying the groundwork” stories. Instead, write stories that involve fully implementing small independent pieces.
Get developers’ eyes on stories before making them playable.
Writing a story alone, even as a dev familiar with the system the story is being written for, is very difficult. Even pro story writers should get developers to look over them after they’ve finished writing one.
Refinement meetings are a great way to accomplish this. Get a group of developers on the team to go over freshly-written stories to provide feedback. Acceptance criteria that may be clear to some may be unclear to others. Some developers may be aware of certain factors that others are not.
However, be careful not to allow refinement meetings to become “story rewriting” meetings. Refinement should mean polishing, not erasing and writing again from the ground up. If refinement frequently involves rewriting of stories, it may be useful to pair on writing them with another developer. This can help ensure that stories are 90% ready to go by the time you bring them in front of a larger group.
Writing Good Stories From a Developer’s Perspective
At the end of the day, no story will ever be perfect, and striving for the perfect story takes more time than it’s worth. But following guidelines like these can help the story writers by reducing the amount of time they spend clarifying, and helps the developers by giving them work they can easily pick up and get working on.