Writing Complete User Stories

User stories can make requirements management a lot easier. They shift some of the communication from up-front documentation to ongoing dialog. That’s the main reason they work so well for agile teams. And agile teams focus on “what’s next?” instead of an ever-changing “what’s everything?” The problem is, when those conversations are working well, it is easy to forget to make sure that what you’ve done is actually enough. Add a small dose of traceability, and you can easily validate the completeness of your user stories.

Three Big User Story Problems

Over the last few years, Alistair Cockburn surveyed a range of teams and identified that they all were facing a similar set of problems. Alistair proposed using use cases to solve those problems. The following list of problems is Alistair’s:

  1. Designers lack the context of the goal that the user is trying to achieve.
  2. The team does not get a early indication of the scope of the project.
  3. Alternate user-behaviors are not identified in advance of the commitment to deliver.

We agreed then (and still do) that well developed use cases can be used to address these issues. Since then, however, we’ve done more analysis of how and when to create use cases and when to create user stories. The primary drivers of the use case versus user story decision still apply, and should still sometimes point you to creating user stories.

Without the context of goals, and without a notion of completeness, your team just has a haphazhard stack of stories. Not only will this reduce their motivation, but it will introduce frustration both for the implementation team and the stakeholders – no one will really know when the job is done. Validating the completness of user stories will allow you to know (and regularly revisit) when you should be done.

When you are creating user stories, you need to be able to address the issues Cockburn identified. You can do that with traceability, and a very small amount of additional documentation.

User Story Metadata

The cool thing about a well-written user story is that it already has metadata within it that makes tracing very easy. A well-written user story, using a format based on the work of Mike Cohn (in User Stories Applied), would read:

As a [role], I want to [do something] [with some frequency] so that I can/will [achieve some goal].

If you were to build a UML Class Diagram to show the relationships that are implicit in a user story, you would get something that looks like the following:

[larger version]

  • The [role] that starts a user story is the persona (lower right corner of the diagram). For products with simple market strategies, identification of personas alone is sufficient. Larger companies and larger products are often trying to address the needs of users in multiple markets or market segments. Each persona you develop is in a single market segment. You may organize your segments regionally or by vertical industry or any other strategy that helps you position your product. You can manage your personas not only as members of market segments, but with a hierarchy of roles.
  • The [do something] you identify is the meat of the user story (top center of the diagram) – what the persona is going to do.
  • The [with some frequency] element tells your team how often a particular user story will happen. This can be represented as an attribute of the user story.
  • The [achieve some goal] component of the user story provides the context (center of diagram) for why a user will be performing an action. The user will be performing the action either to achieve a user goal or a corporate goal. If it is a corporate goal, it will have an internal stakeholder. Ultimately, there should be an internal stakeholder who is not only the beneficiary of that goal, but also the person who “owns” the market segment in which the persona is defined. Sometimes, there will be conflicts in goals, commonly between user and corporate goals. These can also result in conflicting goals between internal stakeholders.

This is what makes things pretty exciting – all of that information is already there, and in your user story. All you have to do now is leverage it.

Goals and User Stories

The following diagram shows how a use case exists to enable the achievement of a goal.

A user story can exist in the same way, just replacing the use case. If you want to do a deeper dive into how interaction design and structured requirements work together, you can use the following model instead:

Note that the diagram above introduces a couple additional concepts. The first additional concept is the practical goal – what the persona is attempting to do because it is the manifestation of a corporate goal. “Take an order quickly” is the practical goal that manifests the corporate goal of “Reduce time required to take orders.” The second concept is that of a scenario. A scenario is an amalgam of user stories (or use cases) that collectively allow the persona to achieve the practical goal. We already represent this without introducing the scenario concept by acknowledging that a single goal is mapped to multiple user stories.

The common element in both approaches is a strong tie between goals and user stories. Focusing on this aspect, you can visualize the relationship as follows:

[larger version]

Note that the acceptance criteria for each user story are called out (so that you can confirm that a user story is “done” and “done well”). Each goal is achieved by enabling one or more user stories, such that the acceptance criteria are met. This is the crux of it, so I’ll write it again, but in bold for the busy people who scan this article.

Each goal is achieved by enabling one or more user stories, such that the acceptance criteria are met.

Note also that multiple goals can be supported by the same user story.

Validating Completeness

The important question that many developers (agile or otherwise) can not answer about their project is “If we do [everything we’ve been asked to do] will we meet our goals?” This is either a failure in communication of context, or a failure to validate completeness of the requirements. You have to flip things around and ask “If only these user stories are implemented, will the goal(s) be achieved?” This is the same process used to validate completeness of use cases – just applied to user stories [Ed: that completeness-validation article was written 3 years ago today. That’s 28 years ago in internet time].

Incremental Overhead

Each user story already identifies the goal(s) it is supporting. The incremental overhead is to recognize that this is “a backwards view” of goal satisfaction and create a simple table that shows the “forward view.”

You are creating traceability from each goal to each of its supporting user stories – but you’re doing it with a simple table (or list, or tree, or whatever). You don’t have to manage your requirements in some big messy repository. If you’re using index cards, consider getting some brightly colored sticky-dots, number them for each goal, and stick them on the index cards to show the relationship.

Then ask the question, for each goal, “Will this goal be achieved if all of the traced user stories (and no other stories) are completed, such that the acceptance criteria are met?”

An added benefit of this simple document is that it markedly improves your engagement with internal stakeholders. You’ve created another opportunity for them to influence the scope of delivery. These stakeholders can identify user stories that don’t map to any goals (you can drop those stories), and by identifying incomplete support, you can collaborate to make sure the missing user stories are identified.

The task of updating stakeholders about progress and managing stakeholder expectations just got much easier – because you can report progress in the context of completed user stories (and therefore manifested goals).

Reviewing Cockburn’s Issues

Does this approach address Cockburn’s issues (listed at the start of this article)?

  1. Lacking the context of goals. This approach explicitly emphasizes that context.
  2. No early indication of scope. The combination of completeness analysis and acceptance criteria provides concrete insight about scope. Note that scope can still change, but this approach is just as effective as documenting requirements with use cases.
  3. Alternate behaviors not identified early. Completeness analysis will highlight when the “happy path” (a.k.a. the normal course in a use case) is not sufficient to achieve the goal. This is really just a variation of the second issue (not understanding scope), but along a variation dimension instead of a coverage dimension.

Conclusion

There is value in being able to document requirements with either user stories or use cases as circumstances dictate. Cockburn identified issues that teams face when dealing with decoupled user stories. His approach of leveraging use cases to solve the issues is perfectly valid. The approach outlined above, tracing user stories, also addresses the issues. As a product manager or business analyst, you need to be able to address the very real issues with either documentation approach.

  • Scott Sehlhorst

    Scott Sehlhorst is a product management and strategy consultant with over 30 years of experience in engineering, software development, and business. Scott founded Tyner Blain in 2005 to focus on helping companies, teams, and product managers build better products. Follow him on LinkedIn, and connect to see how Scott can help your organization.

33 thoughts on “Writing Complete User Stories

  1. Implementation environments have characteristic impedances. These impedances are constraints. In your Goals and User Story figure, where do those constraints come from?

    Your figure referencing personal goals hints at product managers using personas as a means of aligning their own team members. Thanks.

  2. Pingback: Bonnie O'Neil
  3. Pingback: Mike Burrows
  4. Pingback: Paulo Branco
  5. Pingback: Yoav Shapira
  6. Pingback: Guilhem Ensuque
  7. Let’s say we have researched the market and uncovered several market problems. Prospects have told us they want to order classic kid’s toys, and that they haven’t been able to do so in a satisfactory way. They mention that it takes too much time (due to conducting a bunch of searches or perusing classified ads). Thus:

    1. Finding and ordering classic kid’s toys are essential functional goals.
    2. There need to be limits on the amount of time it takes to find and order the toys.

    How do these two items fit into your conceptual model?

    In my conceptual world, the first item would be a functional requirement and could be represented by the identification of a use case or user story. The second item would be nonfunctional requirement and could be represented by the use case’s preconditions, postconditions, and invariants or by the user story’s acceptance criteria.

    1. @Roger (1): As always – thanks for contributing to the discussions here!

      On #1: I guess I see ‘acquiring a classic kid’s toy…’ as a practical goals of the user, which is then manifested as user stories for find and order.
      On #2 – the limits on time, without segue, I’ll agree that it is acceptance criteria for a user story. With use cases, I would identify it as a constraint that applies to the use case.

      With segue in hand, I would say that the surveyed users expressed “too much time” as their criticism, but I would wonder if that’s really what it is. “Too difficult to find” is more representative of the way you described it. I think you could approach solving the problem with several implementation approaches, one of which is ‘make it faster’, but really the goal is ‘make it easier.’ Assuming you had used an example that was explicitly time-dependent (like recharging a defibrillator in under X seconds), I would stick with my #2 response above.

  8. Your model shows scenarios being enabled by implementing functional requirements, followed logically by program and interaction design.

    Could you elaborate on what a functional requirement is in this context?

    The Wiegers view (to which I do not subscribe) is that you define the steps in a use case, and that each of these steps represents, corresponds to, or calls out, functional requirements of the system. A consequence of Wiegers’ view is that functional requirements come after, and are determined by, interaction design (since interaction design determines the steps in use cases). Thus Wiegers’ view is incompatible with your model, since your model shows interaction design coming after functional requirements.

    1. @Roger (2). The ‘functional requirement’ in the included diagram is as Wiegers’ describes in his methodology. Maybe ‘functional specification element’ is a more descriptive term.

      You raise a VERY good point about the challenges of embedding design into use cases, as they imply sequencing. I think that is one of the reasons I’ve migrated to use case briefs and user stories (depending on the teams with whom I’m working) – easier to avoid embedding a procedure or process design in the description of “what a user needs to be able to do in order to achieve a goal.”

  9. Pingback: ellen gottesdiener
  10. Is #2 also a nonfunctional requirement?

    By the way, I do agree that we should probe if “too much time” is really the users’ concern, or if “too difficult to find” is more accurate. Either way, we need to be able to formulate it in quantifiable terms.

    You’re of course preaching to the choir about use cases and the design inherent in fleshing out the steps.

    But the question still remains about the relationship between interaction design and functional requirements in your model. In your model, by “functional requirement”, do you mean what Wiegers means by the term (i.e. functional specification element)? Or do you mean the functional goal of the use case?

  11. Pingback: mkogon
  12. Pingback: Paul Hernacki
  13. Pingback: Fred Steube
  14. Pingback: Barry Day
  15. Pingback: Askar Baybuzov
  16. Pingback: Learn Logic
  17. Pingback: Edson Yanaga
  18. Pingback: Peter Barton
  19. Pingback: Kevin Cory
  20. Pingback: Wii Kuo
  21. Pingback: darrenhamilton
  22. Pingback: SML Data
  23. Pingback: rob
  24. Pingback: HRISjobs
  25. Pingback: Ken Flott SB

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.