Writing Complete User Stories

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.