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 agileteams focus on “what’s next?” instead of an ever-changing “what’severything?”   The problem is, when those conversations are workingwell, it is easy to forget to make sure that what you’ve done isactually enough.  Add a small dose of traceability, and you can easilyvalidate the completeness of your user stories.

Three Big User Story Problems

Over the last few years, Alistair Cockburn surveyed a range of teamsand 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 beused to address these issues.  Since then, however, we’ve done moreanalysis 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 stillapply, 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 thisreduce their motivation, but it will introduce frustration both for theimplementation team and the stakeholders – no one will reallyknow when the job is done.  Validating the completness of user storieswill allow you to know (and regularly revisit) when you should be done.

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

User Story Metadata

The cool thing about a well-written user story is that it already hasmetadata within it that makes tracing very easy.  A well-written userstory, 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 relationshipsthat are implicit in a user story, you would get something that lookslike 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 informationis already there, and in your user story.  All you have to do now isleverage 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 becauseit is the manifestation of a corporate goal.  ”Take an order quickly”is the practical goal that manifests the corporate goal of “Reduce timerequired to take orders.”  The second concept is that of a scenario. A scenario is an amalgam of user stories (or use cases) thatcollectively allow the persona to achieve the practical goal.  Wealready 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 goalsand user stories.  Focusing on this aspect, you can visualize therelationship 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 thatthe acceptance criteria are met.  This is the crux of it, so I’ll writeit 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) cannot answer about their project is “If we do [everything we've been askedto do] will we meet our goals?”  This is either a failure incommunication 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-validationarticle was written 3 years ago today.  That's 28 years ago in internettime].

Incremental Overhead

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

You are creating traceability from each goal to each of itssupporting user stories – but you’re doing it with a simple table (orlist, or tree, or whatever).  You don’t have to manage your requirementsin some big messy repository.  If you’re using index cards, considergetting 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 ifall 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 improvesyour engagement with internal stakeholders.  You’ve created anotheropportunity for them to influence the scope of delivery.  Thesestakeholders can identify user stories that don’t map to anygoals (you can drop those stories), and by identifying incompletesupport, you can collaborate to make sure the missing user stories areidentified.

The task of updating stakeholders about progress and managing stakeholder expectationsjust got much easier – because you can report progress in the contextof 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 issuesthat teams face when dealing with decoupled user stories.  His approachof leveraging use cases to solve the issues is perfectly valid.  Theapproach outlined above, tracing user stories, also addresses theissues.  As a product manager or business analyst, you need to be ableto address the very real issues with either documentation approach.