Beyond Story Cards: Agile Requirements Collaboration

21 Mar, 2005


I gave a presentation at the Rose City Software Process Improvement Network (SPIN) on March 10th, 2005. This is approximately what I said:


[A picture of a story card]

This is a story card. It's a great tool for planning and a lousy tool for communicating requirements. If you've done much work with Extreme Programming (XP), then you may have heard people say, "story cards are a marker for future conversation." But what does that mean? Where do the story cards come from, and what do you do with them when you have them?

In this presentation, I'll be talking about what happens before you create the story cards and what happens after you create them. The one thing I won't be talking about much is the story cards themselves.

Beyond Story Cards: Agile Requirements Collaboration

[A picture of a ripped up story card]

My name is Jim Shore. I've been coaching teams in adopting agile methods since 1999, when we called them "lightweight methods." I started out leading a team using Feature-Driven Development. In 2000, I tried XP, was very successful with it, and I've been helping teams adopt XP ever since. I've worked with a wide variety of companies, and this has given me perspective on what works in XP and what doesn't.

There are a lot of ways to do requirements, and I'm sure there are a lot of ways to do agile requirements. What I'll be presenting today is based on my experience in implementing XP over the last several years. It's a complement to existing requirements engineering techniques and you can continue to use whatever techniques you're currently using for gather requirements.

Why Collaborate?

Lack of user involvement traditionally has been the No. 1 reason for project failure. Conversely, it has been the leading contributor to project success. Even when delivered on time and on budget, a project can fail it it doesn't meet user needs or expectations.

"Project Management: The Criteria for Success"

The title of my presentation is "Agile Requirements Collaboration." I chose that title very carefully. I could have said "Agile Requirements Gathering" or "Agile Requirements Engineering." I chose "collaboration" because user involvement is a key success factor in software projects... in all software projects, agile or not. Agile development values collaboration because it increases your chance of success. I want to emphasize that the techniques I'm going to be talking about are tools for enhancing collaboration, not for creating requirements and throwing them over the wall.

Where do stories come from?

[A picture of a person holding a card to his head]

So where do stories come from in the first place? Well... somebody makes them up. Somebody has to have a vision of what the product is going to be. On an XP project, that person is usually called the "on-site customer." You'll also hear terms like "lead customer" and "product manager." I'm going to call him (or her) a "product manager" in this presentation, because it's more in line with common industry terms.

The product manager needs to have a strong, clear vision of the product, but that doesn't mean he or she is solely responsible for it. The product manager will work with interaction designers, business analysts, real customers, marketers, users... Ultimately, though, somebody has to coalesce all these conflicting views and come up with a clear, unifying product vision. That's the role of the product manager.

The product manager's job isn't easy. He or she (I'll just say "he") has to have a strong sense of vision, to tie all the diverse threads together into a strong, usable product. He has to know the market well and understand what it needs. He has to have the political savvy to juggle all of the project stakeholders' demands, and he has to have the authority to make his decisions about priorities stick.

People like this are very valuable to their companies and it can be hard to get their time. One of the biggest challenges I see with XP teams is difficulty getting a good product manager. To that, I have to say: Yes! Good product managers are expensive. But let's remember that their involvement is a key success factor. Developing software is even more expensive than a good product manager. If your product isn't worth the cost of a good product manager's time, maybe you should re-evaluate whether your software is valuable enough to be worth doing in the first place.

Audience question: What if you don't have anyone with a vision of the product?

I haven't encountered that. What I have seen is that people sometimes aren't sure what they want. They think they know, but when they actually see it running, they realize that they wanted something else. I've also seen people having trouble articulating their vision. I think the frequent iteration-by-iteration deployment of agile methods are an important way to help people understand on what they really want, because they get to see the software actually running.

On the other hand, I was on a team where we were working with a customer and we were showing him the product every two weeks. We weren't sure that we were really delivering what he wanted. Every time we said, "this is really what we're going to deploy!" And he said, "sure, sure." And then, about four weeks from release, we said that again and he said, "wait! That's what we're going to deliver? No, no, it's all wrong."

But it only took us one two-week iteration to change the software to what he wanted. Most of the changes were just user interface changes.

Audience question: I think something that's more common is to have too many people with product vision. How do you balance this?

That's the product manager's role, to balance the competing visions of all the different stakeholders. You need someone with political savvy to do that. I've tried a number of different options, such as allocating each group a portion of the iteration budget, having people justify the value of their stories, and they didn't work well. We spent too much time doing bits and pieces of too many things and never got anything completely done. Ultimately what worked best was just having a product manager make the call.

The "latest responsible moment"

[A picture of a wall of story cards]

The product manager, with the assistance of his team--business analysts, customers, marketers, etc.--creates the stories. But watch out for "story card hell."

Story card hell is when you have 300 story cards and you have to keep track of them all. This doesn't work. Story cards aren't meant to capture all of the details of your product requirements. They're only supposed to be a sentence or two. At most, a paragraph. When you have 300 cards, you lose the ability to understand what they mean. Let's say you have one story card that says "make toast" and another that says "cook bread." Is that the same story? Or are they different requirements for completely different parts of the system? You can't tell, and you lose track of the overall vision because you're surrounded by trees.

A good sign that you're in story card hell is when you start hearing the question, "can we put these in a database?" Every customer I've ever worked with wanted to put story cards in a database. That misses the point of story cards. If you're worried about losing story cards, you're doing too much with them.

That brings us to the idea of "latest responsible moment." "Latest responsible moment" is a core agile idea. The term comes from Lean Software Development. The idea is that you want to put off decisions as long as you can: to the latest responsible moment. But it's the latest responsible moment, not the "last possible" moment. That wouldn't be responsible.

The reason we do this is because putting off decisions is cheaper and results in better decisions. Money we spend tomorrow is cheaper than money we spend today, and between now and tomorrow, we'll learn more things about our environment and the decisions we need to make. Plus, things could change so much that the decision isn't relevant any more. If we've spent the time and effort to make the decision, that money is wasted. So we wait as long as we responsibly can.

Focus on more detail over time

[A picture of a funnel showing increasing detail over time.]

Using this idea of "latest responsible moment," we postpone creating our detailed requirements specification. In fact, we can do the specification for a story at the same time as we actually implement the story. (I'll be talking about that more in a little bit.) We don't need to know every detail about a feature ahead of time. Going into the level of detail is expensive, and if (or when) our plans change, that's wasted effort.

In this graph here (points to slide) I show different levels of detail according to how far away a feature is from being implemented. In most agile methods, we like to deliver a release--at least an internal release--in less than three months. So when you're more than three months away from delivery, all you really need is an overall vision for the release. What market is the software going to serve, what kind of value is it going to provide, what are the basic things the software is going to do. You may have a product vision document or a mission statement.

Once you get closer than three months to delivery, you need to be able to plan the specific features you're going to deliver. So go into more detail. Some people call these "release-level stories," "high-level stories," or "motherhood stories." Either way, you define the major features that your product is going to contain. You can write them on cards.

Six weeks is a good threshold for detailed planning. It's about as far out as you can reasonably predict in detail. Story cards give you the ability to do that detailed planning, so once a feature is less than six weeks from delivery, go into more detail and create stories. If your market and product requirements are particularly stable, you may want to plan a longer timeframe. If it's more chaotic or poorly understood, perhaps less.

And of course, once you've started implementing the story--in this graph, I'm assuming two-week iterations, so that's two weeks before delivery--you need all of the details about the story. That's when you create the specification.

This is an idealized view of the world. In practice, we don't proceed smoothly from vision, to features, to stories, to specification, on the clear, crisp timeframe described here. Reality is messier and it can be hard to know when to go into more detail. But the overall point is valid: you don't need all of the details in advance. You can avoid story card hell by going into more detail only when you need it--at the latest responsible moment.

Audience question: How do you define a "feature?"

You can use whatever definition you're currently using. The important point here is increasing detail over time. I like the definition from Software by Numbers (I'll have a reference at the end), which uses "minimum marketable features:" the smallest set of functionality that has value to your market. You can also think of features as anything the product manager wants the team to do.

Audience question: Can you define the product vision more than three months in advance?

Absolutely. Three months is when I'd start going into more detail and defining features. If you're doing a long term project, with one or two year time frames, then it's a good idea to have an overall vision for the whole project. And perhaps a more detailed vision for the next release, and specific features when you cross the three month mark.

The miracle of collaboration

If you have your product manager and his team working directly with your programmers throughout this process, something amazing happens. I call it "the miracle of collaboration." And it really is a miracle, because time appears out of nowhere.

Now, this isn't easy to achieve. It takes a team that works well together. When your product manager works with your programmers, and the programmers give an estimate, the product manager asks a question that causes every programmer's teeth to grind:

"Why does it cost so much?"

The instictive reaction to this question is to get defensive. "It costs so much because software development is hard, damn it! Why are you questioning me!?"

But there's another approach. It's not easy. But you can take this question, "why does it cost so much?" and think of it in another way. You can think of it as an honest request for information: "Why is this expensive?" And you can answer by talking about what's easy and what's hard.

For example, if the product manager asks for the toaster to automatically pop up the toast when it's done, programmers might say that's really expensive. And when the product manager asks why, the programmers can say, "Well, popping up the toast is easy; that's just a spring. But detecting when the toast is done--that's new. We'll need an optical sensor and some custom brownness-detecting software."

This gives the product manager an opportunity to ask, "But what about all those other toasters out there? How do they know when the toast is done?"

The programmers respond: "They use a timer. But that doesn't really detect when the toast is done. It's just a kludge."

To which the product manager says, "That's okay! Our customers don't want a super toaster. They just want a regular toaster. Use a timer just like everyone else."

And the programmers say, "oh, okay. Well, that won't be expensive at all."

When you do this, when you have honest and open dialog between product managers and programmers, the miracle of collaboration occurs and extra time appears out of nowhere. This happens because product managers don't really know what's easy and what's hard. They might think they do, they might guess, but they're wrong often enough for it to be interesting.

Similarly, programmers don't really know what product managers feel is important. They might think they do, they might guess, but they're wrong often enough for it to be interesting.

Sometimes--not all the time, but often enough to be valuable--these two cases intersect. The product manager asks for something hard that's not super important. He asks for it because he doesn't know it's hard. If the programmers say it's hard, and offer easy alternatives, the product manager can change direction and save time. This doesn't happen on every story, but it does happen often enough to add up. Time appears out of nowhere. It's the miracle of collaboration.

Audience question: What about when your programmers can't give you reliable estimates?

I've found that programmers are pretty good at estimating scope, but not time. Their estimates may be wrong, but they're consistent, so you can tell when something is twice as difficult as something else. This is particularly true when estimating stories rather than features or overall releases.

If your programmers aren't able to estimate consistently, it's probably due to bigger problems. I'd guess they're facing a lot of design debt. Design debt occurs when you sacrifice code quality to meet a deadline. You're essentially taking a loan out on your code. You get some free time, but afterwards, everything takes a little more time to implement, because the code quality isn't there. You're paying interest--high, credit card interest--on your time loan. The only way out is to pay back your principal: spend time to fix the shortcuts.

What happens, though, is that people don't realize they're taking on design debt. So it piles up, and code quality deteriorates. Things start taking longer and longer. Everything takes longer than expected and programmers lose their ability to estimate because they're always running into unexpected problems.

If your programmers can't give you reliable estimates, you probably have a problem with design debt. You need to spend time refactoring and pay back those loans. But don't do it all at once--combine refactoring with implementing new features.

Audience question: When does it make sense to just rewrite rather than refactoring?

I'm reluctant to rewrite. It risky and usually takes longer than expected. You've got a big chunk of time where you're not producing anything of value to your customers because you're re-implementing existing functionality.

On the other hand, software can be so bad that it's cheaper to rewrite than refactor. I'm not sure where the boundary lies. The better I understand refactoring, the more I'm inclined to refactor rather than rewrite. One rule of thumb to keep in mind, from Luke Hohmann, is that rewriting software costs 1/2 the total man-hours of creating and maintaining the software from inception to now. That's often a bigger cost than you might expect.

The requirements fallacy

[A picture of a densely-populated story card]
Image courtesy of

I've talked a lot about what where story cards come from. Now let's talk about where they go.

A common mistake is to think of story cards as little 3x5 requirements documents. I call this "the requirements fallacy." It's a fallacy because story cards make lousy documentation! You end up in story card hell, with lots of little pieces of paper everywhere. It's miserable.

A good sign you're in story card hell is when you're afraid of losing the story cards. As I mentioned before, if you want to put the cards in a database, you're doing too much with them. Another sign is lots of teeny-tiny writing. Another sign is wanting to use bigger cards.

In fairness, this card here (points to picture) is actually taken from the first XP project. But on the page I got it from, there's big red letters saying "don't do this!"

If you don't write requirements on story cards, then where do they go? Actually, XP has had an answer for this from the beginning. Most people forget about it.

Customer Acceptance Tests

Any program feature without an automated test simply doesn't exist. ...Customers write functional tests so that their confidence in the operation of the program can become part of the program, too.

Extreme Programming Explained, p57

Customer tests are how XP expects you to keep track of your stories' details. People don't do this, though, because it's been really hard to do. We have xUnit for programmer tests and test-driven development, but there was no equivalent tool for customer tests.

Some teams created their own tools, but there's a second part of customer tests that's even harder to achieve. Customers are supposed to write and own their tests. So not only do we need a tool for customer tests, we need it to work in a way that customers--that is, our product manager and his team--can understand and use.

In 2002, Ward Cunningham created a tool that enables this. It's called Fit.


Fit is a tool for encouraging collaboration on the details of a story. It's also a testing tool. I focus on the collaboration part, though, because I think people often get too caught up in the testing aspect of Fit. You're not supposed to write your requirements using Fit and hand them to your programmers. You're supposed to work with your programmers to understand all of the details of the story, create tests, and create lasting specifications that you can refer to in the future.

This portion of my presentation was closely based on my Fit documentation trail, particularly "Introduction to Fit" and "Fit Workflow." Please refer to those documents for the remainder of the presentation.


To summarize, you need a visionary product manager to work with your team. If you have one, you don't need to define all the details of your requirements in advance: you can wait until the last responsible moment. If a release is more than three months away, all you may need is a vision for that release. Up until six weeks before implementing a feature, a basic description of the feature on a card may be enough. You'll need stories for planning about six weeks before implementing, and once you start implementing a feature, you should specify it in detail. Fit is a great tool for using word processors to create customer acceptance tests, and combined with some prose descriptions of the tests, a Fit document can also work as your specification.


  • Jim Shore -
  • Fit -
  • "Offing the Offsite Customer"

  • Software by Numbers - Denne & Cleland-Huang
  • Extreme Programming Explained, 2nd Ed. - Beck, Andres
  • Lean Software Development - Poppendieck

I maintain a web site,, that contains articles about agile development and a blog. You can learn more about Fit at the Fit website,

I talked about the importance of having a visionary product manager to work with your team. It can be hard to get people to realize the value of this. I've created a simulation that helps people realize how important working directly with the team is. The simulation is called "Offing the Offsite Customer" and you can find a full set of presenter materials for it on my website. It's a lot of fun.

Software by Numbers is a great book that talks about how you can increase your return on investment just by changing the order in which you deliver features. Kent Beck has released a new edition of Extreme Programming Explained. It's a good book and reflects a lot of experience in helping teams understand XP. Finally, Lean Software Development is my favorite book for understanding the principles that underlie agile methods. I highly recommend it.

I'll be available for additional questions afterwards. Good night.