What Level of Detail Should Be Captured in a User Story?
User Story Examples - Download Now!

I had groceries delivered a few minutes ago. My order included 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 a bit of detail: the variety of apples and how many.

I had to provide just enough detail to ensure I got what I wanted. It is much the same for a product owner when asking a team to build a new feature. Provide too little detail and you won’t get what you want. But providing too much detail brings its own problems.

In this article I’ll discuss the problems with too much and too little detail, how to ensure the right amount of detail is being added, and when detail should be added.

Problems with Too Little Detail

If a product owner writes a user story, or more generally any product backlog item, and includes too little detail, the team won’t know what to build. This means:

  • The team will use valuable time asking questions
  • Team members may not think to ask some questions and so will build something incorrect
  • Estimates are more likely to be wrong as they were based on a partial understanding of the backlog item
  • Commitments to stakeholders or customers based on those estimates are likely to be wrong

As bad as these problems can be, a team needs to be careful not to solve them by swinging to the opposite extreme and adding too much detail.

Problems with Too Much Detail

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 possible to have too much detail in product backlog items.

When excessive detail is included, the time spent adding the unnecessary detail is wasted, as is the money paid to the person adding the detail. Telling my grocery shopper to find me 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.

Getting It Right

It’s unlikely a team will capture the right amount of detail in its product backlog items 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.

When a team 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.

However, this is somewhat like making my shopping list six months in advance. I know that six months from now I’ll almost certainly need to buy eggs and apples, two staples around my home. But starting a shopping list with those items six months in advance is unnecessary.

Starting with Insufficient Detail

When a team starts with too little detail, 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.

This is completely different from when the team is adding too much detail and things seem to be going well.

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.

An Example

An example will be helpful in seeing how much detail should be included. 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

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.

Logging In through Facebook

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?

Get Free User Stories Book Chapters

Get Free User Stories Book Chapters

Please provide your name and email and we’ll send you the sample chapters and we’ll send a short weekly tip from Mike on how to succeed with agile.

Get my chapters now!



Mike Cohn

About the Author

Mike Cohn specializes in helping companies adopt and improve their use of agile processes and techniques to build extremely high-performance teams. He is the author of User Stories Applied for Agile Software Development, Agile Estimating and Planning, and Succeeding with Agile as well as the Better User Stories video course. Mike is a founding member of the Agile Alliance and Scrum Alliance and can be reached at hello@mountaingoatsoftware.com. If you want to succeed with agile, you can also have Mike email you a short tip each week.