clog

There are several schools of thought regarding how to best write user stories. There also seems to be a great deal of confusion regarding how stories are set up - probably because any research into the topic yields such a variety of opinions. Most of us (like myself) also come from a background that emphasizes technical requirements. Stories should emphasize "business success criteria" rather than technical requirements.

What is Business Success Criteria?

I know this sounds like marketing-speak but there's a reason for the semantics. A requirement can exist for any number of reasons. They may be politically motivated or part of another agenda. A requirement may be good or bad. We shouldn't assume that doing what we're "required" to do will lead to success. This doesn't mean anarchy is the answer either, the point is to succeed through collaboration.

You can call it Business Success Criteria, Success Criteria or Business Criteria (sometimes also called Acceptance Criteria). The point is always the same - to describe a path to success. A direction the project can go. There can be several ways to succeed but all "Success Criteria" should point to a consistent goal. If that goal needs to change then the criteria will also need to change. Stories should describe what it will take for a particular piece of functionality to contribute to the success of the business. Usually this is on a small scale at the story level. These small successes add up to successful features which add up to successful products which add up to successful businesses.

Breaking it into Pieces

Story writing usually starts at the feature level. With a set of large stories (sometimes epics) that are usually fully completed features. Most stories should not be fully complete features. These features should be broken up into several stories. Each story can be described as a minimal sub-component that still retains business value (meeting a small but essential set of business success criteria). Creating a new method for a class for example does not measure progress towards meeting business needs. The ability to create a new user, or the ability to modify that user for an application may both provide small yet essential functionality to the product.

Notice that these two items are mentioned separately. Rather than create a "User Manipulation" story there is a story for "Create User" and a story for "Edit User." You can think of these as contributing to a "User Manipulation" feature. Creating a user provides a small amount of business value, editing a user adds a little more. The code paths related to creating and editing are usually very similar (most likely with several shared pieces). They may even be identical, or use fancy metaprogramming for improved architecture. The best architectural solution is the way to go but from the standpoint of describing the business criteria these still are separate scenarios (or sets of scenarios) each providing their own value.

Duplication of Scenario Steps is not Necessarily a Problem Here

The steps involved with validating these scenarios may be nearly identical. That's OK! Duplication in (story) scenario steps is not such a big deal and many argue that it's actually a good thing. Scenarios should be as self-descriptive as possible, so copy/pasted steps may be just what you need. They shouldn't be superfluous however.

If stories are integrated with your acceptance testing framework you should avoid excessive use of metapgrogramming. Being DRY is still good but scenarios should be easy to understand. Scenarios should be clear and concise. The balance doesn't have to be perfect. Remember, you could spend all of your time architecting your test framework but keep in mind the point is to architect the application. At some point the essential specs and scenarios are in place so move on. If you're following Behavior Driven Development then your story scenarios and specs validate your success criteria and communicates how your system works.

As a side note. If you're writing effective tests, compare the amount of time you spend writing tests to the amount of time other projects spend adding bug fixes and the amount of time they require for integration. Which do you think is a more valuable way to spend your time? Would you rather write tests or create emergency patches? One approach requires more discipline but may be more enjoyable in the long run.

Human-Readable Specs and Scenarios

Your stories serve as a communication point between business and development. They should make sense to both developers and the business. Story Acceptance Tests should document the interface of all of the system components. The "Specs" (unit tests for the pre-agile) should describe the inner workings. Think of this as API documentation that a business person could make some sense out of, but more likely to be read by a developer that is new to the system. Sometimes (especially for large/difficult features) you need to describe a component that lies in the middle. This is similar to functional testing. In these cases you can validate functional components using your story testing. These are story tests that are "gray box." You peak into the internals a little but no more than possible. You should not use stubs or mocks for these. These stories should be used with care because they are describing technical aspects of the project. They should be relatively rare.

Tasks or Sub-Stories?

If you follow standard Scrum as defined in works such as "From the Trenches" then your stories may be more like the features I describe above which become broken into several separate tasks.

Advantages of doing it this way are that stories stay "pure." You don't have to worry about technical leakage into stories because these become technical tasks (but then you need to ensure that these tasks aren't superfluous). You can also have separate individuals working on different technical aspects of the story. This may or may not be a good thing. I usually think of it as a bad thing - preferring pairing and approaches involving more collaboration. Sometimes it's an unavoidable project requirement. Tasking may be a better approach for these projects. It also takes less time to write the stories themselves since you don't need to worry about many details. Downsides of tasking are that stories tend to be too large, making estimation less accurate and producing less detailed documentation. Tasks also tend to be redundant, with many smaller stories requiring the same tasks (create a model, create a controller etc). Large/difficult stories involve extensive time in the tasking phase, which can make IPMs drag on for a very long time.

Breaking stories up into sub-stories (creating the feature/story relationship) addresses the disadvantages of tasking but introduces some of its own. Note that the tasking method still involves the breaking up of "epics" just not to the same level of detail. When using this method, almost every story ends up being broken into smaller sub-stories. Story writing takes more time up front since there is more detail at the story level. It's hard to assign more than one person to a small story unless they pair. Stories are usually easier to estimate and track. Less time is spent in analysis during IPMs. Testing is usually easier since they are more targeted (despite the need to test more stories). There is a point of diminishing returns, however, regarding the reasonable lower limit of a story size. I prefer a typical story size that is either a single work-day or half a work-day to complete. Sometimes exceptions are necessary but they should be rare.

Start at the Beginning

If you are on a project that is completely new to Agile then I recommend starting with the reference scrum standard. Only start modifying your workflow/practices as you begin to understand the core concepts of Agile Development, which take much longer to sink in than you think. Most people tend to think in terms of processes rather than practices. This is the wrong approach. Often, when I outline a development workflow to management they don't see it as a workflow at all due to the exceptionally low process. It is much better when good practice keeps the process in check, rather than the other way around. An experienced agile coach can help a project or organization be as agile as possible while still recognizing business realities.

Nothing is Perfect

There is no perfect way to define success criteria, prepare for development, to ensure 100% success or revenue return on the product itself. Inevitably you will run into epics that are difficult to break apart or success criteria that are a little too technical. At some point the rubber needs to meet the road. Give it your best and fix problems along the way. The idea is to have efficient, sustainable and enjoyable development.

For an explanation of how stories should be narrated and scenarios written, the following blog by Dan North is a good description. There are some slightly different approaches out there. Cucumber adopts the "In order to x" style of narrative which puts the emphases on the reason where Dan North describes the "As a x" style of narrative which emphasizes the user. Since the concept of "all stories need a reason" is so important to agile techniques I prefer the "In order to" syntax. The essentials are the same though. There's also a stronger emphasis on shorter stories like I described above now - but the rest should help fill in the blanks.

http://dannorth.net/whats-in-a-story