Architectural manifesto: Adopting agile development, Part 4

Using user stories to define project requirements

In Part 4 of this series, learn about how to define requirements in an agile environment. In all software development projects, everything is based on requirements. Because agile development emphasizes spoken communication over written documents and welcomes changes late in development, traditional methods of writing requirements might not be adequate. In this article, learn about agile requirements and how user stories can help describe them.


Mikko Kontio, Partner, Dazid

Mikko Kontio has a background in software development and consulting. Formerly a director with Softera, a software development company focusing on business portals and telecom-billing solutions, Mikko is currently a partner at Dazid.

01 July 2008

Also available in Vietnamese


Thus far in this series you've learned about agile processes, the benefits of using them, and the requirements placed on the organization that uses them. You've also learned how different types of organizations adapt to agile development and about the different types of stakeholders and what their roles entail. At this point, you might wonder how you're supposed to describe agile requirements in an ever-changing environment.

When handling requirements, you need to plan what features the software will have in the next release and in the future. Consider three cases:

  • If a company is developing its own product with a short-term scope, such as adding features and seeing how users like them, then requirements can be fairly simple and discussed as they are developed.
  • If the company needs to make road maps of future features, then they need to have tools to discuss the work efforts, cost, and design issues. In this case, the level of detail will be greater.
  • A company decides to outsource the development of the project. A team outside the company will do the actual developing, and the buyer wants to get a fixed price for the deal.

As you learned in previous columns, fixed-price deals and agile development don't go well together. A better choice is to buy the developing team for a certain period of time, and have them develop as much as they can in short sprints. For example, the team could have three members with a six-month time frame. During this time, the team might be able to do 10 two-week sprints.

There are two kinds of time frames for the requirements: short term and long term. Agile development is excellent for short-term requirements, because the requirements can be thoroughly discussed before they are implemented. Agile development highlights spoken communication over written documents and welcomes change. With short-term projects, this is a good thing because you need to handle only a small number of requirements. User stories are excellent for capturing the user needs in an understandable format.

In the long term, you need to address the likeliness of change and handle the requirements only at a general level. User stories also work in this case. But you have to remember the time scope, and leave the requirements that will be done in later sprints on a more abstract level.

We will again use Scrum as our reference methodology. See Resources for more on Scrum.

Agile requirements

Agile development emphasizes spoken communication over written documents, and welcomes change even late in development. In the non-agile world, requirements are gathered, written, and thoroughly analyzed before development even starts. The documents are often long, and the requirements are described in detail to make sure that important data is captured. In some cases, the writer of the requirements never meets with the development team to discuss the requirements and the software. Sometimes this is the only possible option due to laws, contracts, and so on.

Introducing changes late in development presents challenges, such as change management or contract issues. Instead of doing something the customer really wants, in a worst-case scenario, the customer and developer must renegotiate the contract. This renegotiation leads to a situation where, at the start of development, some requirements are outdated, and high- and low-priority requirements are treated equally because of the contract.

In agile development, the goal is to write the requirements in such a way that representatives of both the customer and the developers can discuss the requirement or function. Discussion enlightens the possibilities, difficulties, and costs to the customer, and it relays the business situation to the developers. Through discussion the customer can prioritize some requirements over others, and the team can work out details for the most important requirements before they are implemented.

What happens if the future requirements demand something that can't be done with the current architecture or technological choice? That is considered a change, and agile development welcomes change. If the requirement was not known three months ago, either something has changed in the business, or the priority of the requirement was previously not very high. If the change requires massive changes in the software, it will be implemented only if it's very important to the business. The expertise of the development team plays an important role in this situation. The software architecture should be easy to modify and expand in the future. A good team will make sure that unforeseen changes cost the customer as little as possible.

User stories

A user story describes functions a user would like to have in the software. The user story consists of three parts:

  • A written description
  • Conversations about the story with users
  • Tests that you can use to determine that the story is complete

User stories work best if the users write them. They know the language of the business, and they have a more intimate relationship to the software because they use it.

When the user story technique was developed, each story was written on a card, so they were called story cards. The card was easy to pick up while being discussed. It was easy to add comments and clarifications on the card. It also restricted the length of the story. Listing 1 shows a sample user story of a financial planning application.

Listing 1. Sampler user story
A user adds a new budget to the system to start financial planning.

The requirement is that a user must be able to add a new budget to the system. This story raises some questions, such as:

  • Does the user have to be logged in?
  • What values are stored about the budget? Title? Time frame? Name of the person?
  • Who is responsible for the budget?

Quite often, additional information can be expressed as new stories. You can also add information to the card, such as A user adds a new budget and gives it a title.

The user story is not a contract, though, so you shouldn't worry about getting all the details into the story. Rather, you should discuss these details with the customer, and write them down in the tests. If you're using cards, flip them over and write on the back. Listing 2 shows some tests for the user story in Listing 1.

Listing 2. Tests for sample user story
Add a new budget with title "Budget for 2008"?
Add a new budget with responsible person "Dave"?
Add a new budget with empty title?
Add a new budget with really long title?

As you go through the requirements with the customer (or a customer proxy), you begin to form a list of requirements. In Scrum, the list can be treated as the product backlog, which must be prioritized and then split into sprints.

The following structure is a good framework for writing user stories.

As a [type or role of user]
I want to [perform some task] 

So that I can [reach some goal]

In Listing 1 you see that the user story has the role of the user, the task, and the goal. Modeling user roles is an important part of gathering user stories. You must model the roles to find out what other limitation the task might have. For example, a user story that describes listing all budgets in the system would work quite differently if the user were a company administrator (who could see all the company's budgets), a basic user (who could see only user's own budget), or the application administrator (who might see them all).

Goals are also important in understanding the domain of the story—why the user wants to perform the task. In the sample story, the goal is to start the financial planning. It gives the developers a sound reason why this function is important for the user.

Characteristics of good user stories

A good user story is defined by several characteristics:

Stories should have as few dependencies as possible, because dependencies can cause problems in prioritization. For example, if one story has a high priority and it is connected to another story with a low priority, selecting stories for a sprint might be difficult.

Another problem arises with estimating work efforts. If two stories have dependencies in their implementation, implementing the first one might take five days and the second one could be done in a day. It's hard to estimate this by looking at the stories.

Stories are not contracts. They are short descriptions of functions and should be reminders for discussion. Details of the stories are to be discussed between the customer and the development team.
The stories should be valuable to someone in the customer's organization (users, purchasers, support team, and so forth).
Work efforts are important for the sprint planning, so developers should be able to estimate, or at least take a guess at, the work efforts. There are typically three reasons why the story is not estimable:
  • Developers don't know enough about the domain.
  • Developers don't know enough about the technology.
  • The story is too large.
All of these obstacles can be overcome to avoid big mistakes.
Stories should not be too long. If the story is too short, though, you cannot use it in planning. The length of the story is largely dependent on the skills and experience of the team, the customers, and their experience working together.
All stories should be testable to make sure that they can be implemented. As in non-agile development, testing problems occur mainly with nonfunctional requirements or quality attributes. It is really easy to write nonfunctional requirements that are not measurable and thus not testable. The developer should always keep this in mind.

Product backlog

The product backlog contains the features and functions the product owner wants to have in the product in the future. For each sprint, a group of functions is selected from the product backlog and placed in the sprint backlog. The sprint backlog will be implemented in the sprint.

To help estimate how much work a user story will entail, you can use story points or work days. The goal is to have some sort of estimate of how much work the story requires to be able to make a reasonable sprint backlog. Of course, the stories are discussed with the team before they agree on the sprint content. The team then composes the sprint backlog by going through all the selected user stories and defining the development tasks required to implement them.


In this article, you learned how agile requirements differ from traditional, thoroughly written requirements. In agile development, requirements are gathered in a format that supports change and spoken communication.

User stories have become a common method to describe requirements in agile projects. User stories are short stories that answer the basic questions of who, what, and why. Good user stories are independent, negotiable, valuable, and testable. If the development team is using Scrum, the product backlog in Scrum contains the future functions (basically a list of user stories).

Stay tuned for the next installment in this series, which will go through an example user story and the requirement process.



  • Check out the other parts of this series on adopting agile development:
    • Part 1, Is agile development right for your organization? (developerWorks, Mar 2008)
    • Part 2, Understanding the different facets (developerWorks, Apr 2008)
    • Part 3, The role of agile stakeholders (developerWorks, May 2008)
  • Read Wikipedia's discussion of user stories.
  • Read more about Scrum, and Adaptive Project Management Using Scrum.
  • User Stories Applied: For Agile Software Development by Mike Cohn explains how to develop flexible, practical requirements that work; save time and develop better software that meets users' needs; gather user stories—even when you can't talk to users; leverage user stories as part of planning, scheduling, estimating, and testing.
  • Browse the technology bookstore for books on these and other technical topics.

Get products and technologies

  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=Architectural manifesto: Adopting agile development, Part 4