How to best manage user stories in your agile development projects

User stories serve several important purposes for agile development teams. In this expert response, Sue Burk explains the full range of uses for user stories, discusses how to best document requirements details, and offers different approaches to making the most of user stories.

In Agile environments, are the user stories the requirements? Do the details get documented somewhere?

Often, the details are documented. User stories are small, concise statements of the functionality that is needed for the agile team to deliver value to a specific stakeholder. User stories can have multiple uses on an agile project, including:

  • Prioritizing user needs
  • Estimating and planning product delivery
  • Additional analysis
  • Generating user acceptance tests
  • As a metric for measuring delivered value
  • As a unit for tracing related requirements
  • As a unit of project management and reporting

In user stories, how much detail is enough? “Enough detail” means just enough so that all the stakeholders are clear about what the business needs are and what the delivery team will deliver. Anything left to guesswork creates the risk that someone will make assumptions about the details. These assumptions may unwittingly constrain or direct business and software development activities in ways not intended by the business.

If an agile team’s stories are long or vague, the team first needs to slice them into scenarios. (You can find out more about slicing user stories in Ellen Gottesdiener and Mary Gorman’s recent article Slicing Requirements for Agile Success.) Once you have your stories brief and concise, it’s time to clarify the details with the customer -- the “product owner,” in Scrum terminology. 

Of course, you won’t try to talk to the customer about all the stories at once. Instead, you will conduct this conversation just in time for each prioritized user story within your iteration or release. 

Suppose you’re on a small, co-located agile team with domain expertise. When you talk to the customer about the details of a user story, you might write notes or drawings on a whiteboard or flip chart and then photograph it as a record. Or you might immediately use what you learn to develop executable tests and code. Either way, you can refine your work further by using the feedback from the product owner during acceptance testing.

This method may not be sufficient for capturing details if the team is distributed, supports a regulated business, requires hand-offs to other teams, or lacks rich knowledge of the business domain. In that case, you may want to explore requirements details by adding lightweight analysis models (e.g., a data model, a state diagram, prototypes, and mockups), along with user acceptance tests.

Taking a test-driven approach to exploring user stories allows you to obtain just enough detail without incurring the overhead of extensive documentation. Working with your customer, you devise scenarios for each story and then write concrete tests for each scenario. Define a set of concrete examples that will prove that the software delivers what a user story intends. Each test includes a context, inputs, and expected results (I like the Given/When/Then format popularly known as Behavior Driven Development). Requirements management and testing tools are handy for capturing, tracking, and tracing the user stories and corresponding tests.

Next Steps

How user story mapping can guide your Agile project

Dig Deeper on Topics Archive