Agreeing on Terms
Before I answer that question, let’s make sure we agree on our terms. As I describe in my blog "Demystifying Product Backlog Concepts," the product backlog can contain different types of product backlog items (PBIs): features, defects, technical work, knowledge acquisition, and so on. Users stories aren’t a type of product backlog item; they are a representation format that is typically used for customer-facing features.
Here is an example feature written in the format of a user story.
If you imagine user stories being written on index cards or sticky notes, then the left side of this picture (the front of the card) is the core of the user story. This part defines who is getting the value, what they are getting, and why it is important to them.
The right side (the back of the card) are the conditions of satisfaction, which I define as the conditions under which a product owner would be satisfied that a product backlog item is done. Conditions of satisfaction are the acceptance criteria that clarify the desired behavior.
A Continuum of Details
Now back to the original question: How detailed should those conditions of satisfaction be?
You can answer this question along a continuum of details. On one end of that continuum is “no details,” just move the stories into a sprint without any details and then let the development team members ask the product owner clarifying questions when they arise.
In the above example this would be equivalent to not providing any details on the back of the user story card. So the story would essentially be “Add a new prospect to the lead management system,” and no more. This approach might occasionally work, but chances are the stories won’t be in a ready state before sprint planning and during sprint execution there likely will be many times the development team gets blocked waiting for clarification from the product owner.
The other end of the spectrum is “complete details,” meaning everything that the product owner could possibly imagine that the development team members might need to know in order to complete the stories. In the above story, some additional information that might be included in an attempt to provide complete details could be field-level validation, a screen mock up, and a description of alternative or exceptional scenarios (as well as much more).
Adopting a “complete details” approach would force the product owner into creating the equivalent of a detailed requirements document up front, when all concerned have the least possible knowledge they will ever have about the current development effort.
Barely Sufficient Level of Detail
So along the continuum from no details to complete details where should you draw the line? Clearly it should be somewhere between the two extremes. However, early on when you are just getting started writing your user stories, you probably won’t know where to draw the line to have ready stories and achieve good flow during the sprint.
My advice, as shown in the following image, is to draw a line representing the barely sufficient amount of detail that is necessary to get your product backlog items into a ready state. If you are bothered by the term barely sufficient, then substitute good enough.
And, as a general rule for establishing the initial barely sufficient line, I suggest teams favor a point closer to the no details side of the continuum.
Inspecting and Adapting to A Good Level of Detail
Let’s say that the amount of detail shown on the user story at the beginning of the blog is our first approximation of what we mean by barely sufficient. Although it seems like a reasonable starting point, you won’t know for certain whether that amount of detail is right for our project until we actually try to design, build, and test the feature. That's OK. We shouldn't expect to get it perfect the first time.
In fact, if you follow my advice and choose to err on the side of too little detail, chances are that your first placement of the “level-of-detail” line will be too far to the left (not enough details). Don’t be concerned about this outcome. As I discussed in my blog "Why Be Perfect Up Front When you Can Be Agile," you will start by drawing a reasonable line, get feedback on how well that level of detail worked, and then inspect and adapt and redraw the line on the continuum in a direction that you think will improve your teams outcome (ability to get the work done to the satisfaction of the product owner).
Let's suppose that you implement the user story described in the beginning of the blog. And let's further imagine that you learn that not specifying the field-level validations (e.g., how many characters and what types of characters are in the “name” field) blocked development and testing during sprint execution. If so, in the next sprint you increase the level of details on user story conditions of satisfaction by providing field-level validation information (essentially moving the barely sufficient line more to the right in the above continuum picture).
Perhaps after completing the sprint where you included field-level validations you learn that not having a screen mock up was an impediment to good flow during the sprint. So, should you include mockups as part of the conditions of satisfaction? In some organizations the screen design is considered part of the definition of ready for a user story and thus would be included in the conditions of satisfaction. This means that at the end of the sprint one of the acceptance criteria will be to verify that the implemented feature uses the screen design provided with the user story. In other organizations, screen design occurs as part of the work during the sprint and no such mock up is provided as part of the conditions of satisfaction with the story. So, whether to include a screen mock up or not is another way for you to vary the level of detail associated with the conditions of satisfaction.
Finally, what about alternate cases or scenarios associated with the story? For example, in the above story, how should the lease management system respond if the property manager tries to enter a prospect that is already in the system? No such detail is currently provided. There can many such alternate scenarios or exceptional conditions. Should the user story specify some or all of them? This is yet another way of increasing or decreasing the amount of detail associated with the conditions of satisfaction.
There is no universal answer to how many details should be included in user story conditions of satisfaction. Teams that are just getting started with agile and user stories won’t know exactly what is the proper level of detail. I have found that a good approach is for the team to define what it considers to be the barely sufficient level of detail necessary to get stories into the ready state and promote good flow during sprint execution. Then, move these stories into a sprint and see how well the team is able to complete the work given the amount of detail provided. By inspecting the results during the sprint retrospective, the team can choose to adjust the level of detail to see if that change is helpful in being better able to complete the work in a sprint. After several (usually less than a handful) of sprints, the team typically converges on a proper level of detail to reliable get the work completed.