An extremely common mistake people make with writing good user stories has to do with including the right amount of detail at the right time.
It's an important balancing act. Bring an agile user story into an iteration before it is sufficiently understood and there will be too many open issues for the team to complete it within the iteration. But try to resolve every open issue and add every little detail to a story and you end up with functionality that takes far too long to make it into the hands of users.
Like Goldilocks and the bears, we don't want items in the product backlog with too little or too much detail—we want detail that is just right.
The Right Amount of Detail for User Stories
To understand the right amount of detail for user stories, or more generally any product backlog item, consider an example.
I had groceries delivered a few minutes ago. My order included five apples. I requested Honeycrisp apples, and that’s exactly what I got.
I didn’t specify that the apples should have a diameter of exactly three inches. I didn’t specify apples that were firm and not moldy.
When placing the order, I had to provide the right level of detail to ensure I got what I wanted: the variety of apples and how many.
It is much the same for a product owner when asking a team to build a new feature. Product owners need to provide the right level of detail, at the right time, to get what they want
Problems with Too Little Detail
If a product owner writes a user story and includes too little detail, the development team won’t know enough during sprint planning to understand what to build. This means:
- The team will use valuable time during the sprint asking questions
- Team members may build something incorrectly
- Estimates are more likely to be wrong
- Commitments to stakeholders or customers based on those estimates are likely to be wrong
As bad as these problems can be, scrum teams need to be careful not to solve them by swinging to the opposite extreme and adding too much detail.
Problems with Too Much Detail
"User stories are written with too much detail" might at first sound like an oxymoron—you can’t be too rich, too thin, or have too much detail on a product backlog item. Except it is entirely possible to have too much detail in product backlog items.
When excessive detail is included, the time and money spent adding the unnecessary detail is wasted. Telling my grocery shopper to find apples that were three inches in diameter would have been a waste of my time and the shopper’s, unless there was some rare circumstance that truly required apples of precisely that diameter.
Perhaps worse than the wasted time and money is that developers may feel artificially constrained by the excessive detail. Suppose I’ve provided a grocery shopper with the following specification:
- Buy five apples
- Honeycrisp variety
- Three inches diameter
- Firm
- No bruises
What will the shopper do if there are not five apples that meet all these requirements? Is it OK to select a slightly larger last apple? Or is the three-inch diameter most important? Would I prefer a larger apple without bruises to an apple of the perfect size with a bruise?
This may seem trivial with apples. It’s not when developing a product. When a team is provided a lengthy list of requirements a user story must fulfill, many teams will resist deviating from anything on that list even if a better way of building a feature is possible.
Get User Story Details Right, Iteratively
It’s unlikely a team's product backlog will be detailed perfectly right off the bat. This means the team will likely have to iterate toward the right amount of detail.
I find it much easier for team members to find the right amount when they start with too little detail. Maybe start by filling in the user story template with the bare minimum amount of product features and detail.
When a team instead starts with too much detail, team members may not even notice there’s a problem. Remember, the big problem with excessive detail is the time is wasted collecting that detail before it’s needed. A team may, however, not notice this or think of it as wasteful. Team members may just see their iterations running smoothly, with very few last-minute discoveries derailing them, and be content with that amount of detail.
When a team starts with too little detail, though, they’ll notice the problems it creates. Team members will struggle to finish all items within the iteration; there are too many open issues to be resolved. They may feel they are being asked to estimate something when they know only the basics of what will be required.
Because these are real problems with obvious implications, it is clear to team members when they’re gathering too little detail. And the solution is obvious: gather more detail.
By starting with insufficient detail on its product backlog items, a team will be able to quickly inspect and adapt to find the right amount of detail.
What Does the Right Amount of Detail Look Like?
When a product backlog item includes the right amount of detail, team members will feel as though they were just barely able to finish the item during the iteration. They’ll feel as though enough details had been determined in advance but not so many that the creativity had been removed from the iteration.
In striving for these feelings it’s important to not tip over to the side of adding too much detail too early to product backlog items.
Example of a Detailed User Story
It will be helpful to look at an example detailed user story. Suppose a team is building a new application and is working on a user story that says members are allowed to log into the system. Various acceptance criteria, otherwise known as conditions of satisfaction, are identified for that story stating that a user:
- Must provide a unique email address
- Must specify a strong password
- Can log in through their Facebook account
We can learn several lessons from this example user story.
Lesson 1: Not Everything Needs to Be Known Before Starting
When thinking about working on a user story, it is useful to realize that the team doesn't need to know everything before it starts a story. All open questions need to be answered before a story is finished, but not all need to be answered before the story is started.
Consider the requirement to provide a strong password. Very little detail is provided in that statement.
How long must the password be? Does it need to include any special characters? Which special characters? How many? Can a user change their password to a previously used password?
The team members who will code and test this user story need to know the answers to those questions. But they do not need to know the answers to those questions before starting on the user story that enables users to log in.
The answers can be uncovered after team members begin working on the story. Perhaps these details are added in the hour after a programmer and tester begin work on the story. They go talk to the company’s chief security officer with a list of questions and return knowing the detailed answers.
The key is that “Must specify a strong password” is sufficient when the story is first written. The details about what constitutes a strong password can be determined later.
(I’m open to being wrong about that in the case of some super-duper secure system. But, for the majority of systems most of us log in to, I’ve described the situation accurately.)
Lesson 2: Too Much Detail Too Early Is Harmful
Another acceptance criterion for our log in story said that users could log in through their Facebook accounts. This is an example of providing too much detail too early.
When the log in story was first written, it would have been better to state merely that users can log in through social media rather than users can log in through Facebook. For the most part, there would be no reason to determine upfront that Facebook is the only additional way a user can log in.
The Joy of the Right Amount of Detail
Learning to include the right amount of detail on product backlog items is a strong indicator that a team and its product owner have really grasped what it means to be agile.
Everyone will realize that by trying to add the right amount of detail, sometimes too little will be included. And that means some product backlog items won’t be completed within their iterations.
But that will be fine because everyone will understand that avoiding that would require sometimes including too much detail. And the team, product owner, and stakeholders will be aware that adding too much detail is worse than occasionally missing an item because too little detail was included.
How Is Your Team Doing?
How is your team doing at including the right amount of detail? What problems have you seen from including too little or too much detail? What has your team done to include the right amount of detail?
