The Agile Architect

Defining Your Product with Agile Stories

Building the right product is critical for success. Our Agile Architect shows you how to write carefully crafted stories to define your product and drive agile development. 

• By Mark J. Balbes, Ph.D.
• May 24, 2012

There is a common misconception that agile software development is a shoot-from-the-hip, cowboy style of development where anyone can do whatever they want at any time. With these columns I've been trying to show that, in fact, agile software development is one of the most disciplined software development methodology yet created.

I've spent a lot of time on the engineering side of agile, talking about techniques like test-driven development and pair programming. I've also talked about the project management side, dealing with metrics and schedules. What I haven't talked about yet is the product management side of agile. We're going to rectify that today.

Story writing is perhaps the hardest part of agile software development, and yet it enables everything else. The idea is to break down the project into small stories, each of which is self-contained, provides a small amount of value to the end user, and represents a thin vertical slice through the layered application design. The story should be big enough that it is worth the overhead of managing as a separate story, but small enough that it can be developed quickly in order to get rapid feedback from the customer. Typically, you want stories to be able to be implemented in a day or less. If it starts taking three days, you are investing too much time before getting user feedback and you should look for ways to split the story, even if the split is artificial or forced.

How To Write Agile Stories, Part 1: The Mechanics of Story Writing
There are two common canonical forms for stories. I've worked on projects that use one or the other. I've also worked on projects that use both since they serve different purposes. Let's see why...

The first common canonical form tells the story from the user perspective. It clearly lays out why the user wants this functionality in the system without giving specifics. It is written in the narrative as "As a <some kind of user>, I want to <do something> so that I can <get value>. "

The second common canonical form is used to describe acceptance criteria for a story. The acceptance criteria serve multiple purposes. They are used by the developers and testers to know when a story is done. They also act as documentation for the behavior of the system, e.g. for technical writers and customer service.  The acceptance criteria for a story take the form of "Given... When... Then..." A single story may have multiple acceptance criteria.

Here's an example:

Narrative:
As an author, I want to be able to check the spelling in the article I am writing so that my writing looks professional.

Acceptance Criteria:
Given a document with no spelling errors
When I choose to check the spelling of the document
Then I am presented with a message telling me all words are spelled correctly.

Given a document with one spelling error
When I choose to check the spelling of the document
Then I am presented with a message listing the misspelled word.

Given a document with multiple spelling errors
When I choose to check the spelling of the document
Then I am presented with a message listing all of the misspelled words.

Given a document with zero or more spelling errors
When I choose to check the spelling of the document
And the spelling algorithm fails
Then I am presented with a message to that effect.

Notice that I did not specify with any level of detail how the message gets displayed to the user, whether in a dialog box, on the screen or some other mechanism. If that mechanism is well known, I might include it in the story. If not, I'll write the story and worry about figuring out the specific mechanisms later. I probably also want any misspelled words to be underlined in red, but that's a different story with its own acceptance criteria.

When thinking of acceptance criteria, it is often useful to use the "zero, one, many" rule. Think about what happens in the system if nothing meets your criteria, if one thing meets your criteria, and if multiple things meet your criteria. Also, consider error conditions especially if you want special handling for those conditions. If the special handling is too special, you might want to break it out into its own story.

Remember that the example above is just that, one single example. When you are writing your stories, do what makes sense for your product and your team.  As long as the story is small and provides real value to the end user it is a valid story.

So what's not a valid story? Anything that doesn't provide value to the end user, e.g. "As a software developer, I want to write a SQL query that checks all submitted words against the dictionary table so that I know which words are not in the database." While you will certainly have to implement something like this for spell checking functionality, this non-story does not provide value all the way back to the end user. This anti-example is a task that will have to be done as part of the real story.

Story Sizing
Once you have one or more stories, you can estimate the level of effort for each. Humans are really bad at estimating absolute sizes. However, we are great at estimating relative sizes. When we size stories, we only need to concern ourselves with relative sizes. This allows us to calculate important metrics like velocity. (See my column, "Agile Deadline Ahead: Calculating Velocity.")

There are a lot of different methods to size stories. Perhaps the most common is to use a process called Planning Poker defined in eXtreme Programming. Planning poker allows the entire team to participate equally in sizing the stories. At the end of planning poker, each story has a relative point value. This combined with the team's historic velocity determines the absolute level of effort for the set of stories.

When To Write Stories
Stories can be written at any time during a project. This is one of the mechanisms that agile practices give us to adapt to change. As we learn about the system we are building and the people who will use it, we get new ideas for new features, more effective workflows, and more usable user interfaces.

Depending on the outside forces on your development project, you may choose to front-load writing stories or defer until the last responsible moment. For example, you may be working on a project where it is very important to understand what your end date will be. (I know it's unrealistic. No one ever cares about the end date for a project.*) In this case, you may choose to write as many stories as you can as quickly as possible at the start of the project to determine an initial scope for the work. As the team velocity is established over the first few weeks of the project, you can easily extrapolate an end date.

(*Yes, that was a joke.)

On the other hand, if you are trying to build something more innovative, you may not really know what you are going to build when you start the project. In this case, you may be better off writing the stories as you need them. Don't write stories too far into the future because they may get invalidated before you are ready to implement them.

How To Write Agile Stories, Part 2: The Art of Story Writing
Giving you the mechanics of story writing was the easy part of this column. Now comes the hard part, something that I can't easily teach but rather comes from experience.

The hardest question to answer is, "What are my stories?" In other words, as the customer/product manager/business analyst, how do I take my grandiose ideas and break them down into these bite-size chunks of value? All I can tell you is how I do it and let you learn the rest from your own experiences.

First of all, don't think that any of this precludes the need to do your up-front research about what your customer's needs and desires are. You have to start with that vision for the product first, even if it is not very well known. In other words, ya gotta start somewhere. Before launching into a development cycle, you may want to spend time on user experience activities. Techniques like contextual design, paper prototyping and usability testing are important activities for understanding your user needs and identifying effective ways for them to interact with your product. The outcome of these and other product definition activities will drive the creation of your stories.

For me, once I have the vision of what I want to build, I like to create a simple headline for each story in a plain-text document. In the example above, the headline might be as simple as "One-Click Spell Check." As I build up my headlines, I can start to organize them into sets of headlines that have some kind of affinity to one another. For example, I might group all of my spell check and grammar check headlines together. This lets me start to more concretely define the end product and think about what other stories are needed for completeness.

Once I've got this larger definition for the product, I will regroup my stories, this time with an eye to the order in which I think they will be implemented. I do this so that I can start thinking about what minimal set of functionality I will need in each release. (Remember that we like to release as often as possible, but not more often, on agile projects.) I may have 20 stories focused on spelling and grammar checking but decide that five are enough for a first release. At this point, I have enough information that I may ask the team to give a rough size to each headline. This draws the rest of the team into the creative process, gives me good feedback on whether I'm making sense, and starts to flesh out the size of the releases.

When I'm happy with the headlines, I will start to write the complete stories with narratives and acceptance criteria for each. Depending on the size of the project and the demands of the business, I may write all of the stories in a release or I may write just enough to stay ahead of my developers, writing just a handful of stories at a time. The further ahead of development I write the full stories, the more chance that I'm wasting my time on a story that will be invalid by the time we get around to implementing it or deciding not to implement it. On the other hand, if I can get a good chunk of stories written for the release, it may generate new stories that I hadn't thought of. Working ahead also gives the team a chance to give more accurate story sizes since there is more definition to each story. Each project is different and I do the work at the time it makes sense for that project.

Stories as Tests
I've discussed in many previous columns the importance of automated testing to enable truly agile development. A comprehensive suite of automated tests allows you to fearlessly modify your software without the concern that you will break existing functionality.

What does testing have to do with stories? I'm glad you asked!

There is a very powerful movement in the agile community to drive automated testing from the stories themselves. In fact, the idea is to take the stories as written in English and compile them into automated user acceptance tests. The current preeminent tool for this is Cucumber. Cucumber tests, "cukes" for short, are simply the "Given, When, Then" acceptance criteria we discussed earlier. The Cucumber software compiles this English into automated test skeletons in Ruby, Java or other languages. The developers fill in the blanks of the code to exercise the user interface of their application. There are a lot of tools to help with this and the team quickly builds up a domain-specific language for the product. The amazing thing about this paradigm is that your developers and testers are no longer writing automated user acceptance tests. Your customer and users are doing this directly!

Final Thoughts...
A good set of stories propels your development forward. It allows the team to focus on implementing and testing one story at a time. It allows the customers and users to try out the system as it is being built and provide positive feedback, constructive criticism, and course corrections while there is still time to act on them. Story sizing allows the project management team to track the progress of the project and calculate a very realistic, highly reliable completion date. And since stories are implemented in order from those providing the most business value to least, the project can be shipped at any time, knowing that it contains the most important features.

In short, carefully crafted stories are the driver and enabler for all other agile disciplines.