Stories

Audience

Whole Team

We plan our work in small, customer-centric pieces.

Stories may be the most misunderstood idea in all of Agile. They’re not requirements. They’re not use cases. They’re not even narratives. They’re much simpler than that.

Each story is a reminder to have a conversation.

Stories are for planning. They’re the playing pieces of the planning game. That’s it! Alistair Cockburn calls them “promissory notes for future conversation.” Each story is a reminder to talk about something the team needs to do. They’re written on index cards, or the virtual equivalent, so you can pick them up, move them around, and talk about how they fit into your plan.

Allies

Whole Team

Team Room

Because stories are just a reminder to have a conversation, they don’t need to be detailed. In fact, detailed stories are a sign that people are missing the point. You’re supposed to have a whole team, a team room, and talk together regularly. The story is the reminder. A way of sparking conversations about the details.

Although stories are supposed to be brief, it’s okay to add additional notes when it’s helpful. If there’s something important you want to remember, or a technical detail that you need keep track of, go ahead and jot it down. Just don’t feel obligated to add more detail. The card isn’t meant to be a requirements document. Just a reminder.

Cargo Cult: Writers’ Workshop

“We need training in how to write better stories,” Rafaella moans. “I’m sick of our team building the wrong things.”

You’re not so sure. “But aren’t stories just supposed to be a reminder to have a conversation?” you ask. “Maybe we should talk to our product owner more often, ask them questions, show them what we’re working on—you know, get feedback on whether we’re building the right thing as we work.”

Rafaella snorts. “Yeah, good luck with that. No, we need to get product owners to Write. Better. Stories. Everybody’s complaining about it. I’ll see about shaking loose some training budget. I’m sure I can find a trainer who will tell POs what they need to hear.”

How to Create a Story

Ally

The Planning Game

Everything that your team needs to do, other than normal overhead, needs a story. That’s how work gets prioritized. No matter your role on the team, when you learn about something the team needs to do, write it on a card and queue it up for discussion in your next planning game. You just need to write enough to start the conversation and jog people’s memories in the future. For example:

• “Warehouse inventory report”

• “Full-screen demo option for job fair”

• “Customizable branding on login screen”

You don’t have to use a story template.

Some people like to use the Connextra template for writing stories, like this: “As a (role) I want (something) so that (result).” You’re welcome to use that format, if you want, but it’s not required. Connextra created that template as an experiment, to help remind them of how they were serving their users. You’re free to try your own experiments, or to just jot down a few words.

Although stories are short, they still have two important characteristics:

1. Stories represent customer value and are described in customers’ terminology. They describe work that customers recognize and value, not implementation details. This allows your on-site customers to make informed prioritization trade-offs.

2. Stories have clear completion criteria. It doesn’t have to be written on the card, but on-site customers need to understand what it means for a story to be “done” and be able to describe it when asked.

The following examples are not good stories:

• “Automate integration build” doesn’t represent customer value.

• “Deploy to staging server outside the firewall” describes implementation details rather than an end result, doesn’t use customer terminology, and would likely be difficult for on-site customers to prioritize. “Make demo available to customers” would be better.

Customer Value

Stories need to be customer-centric. Write them from customers’ point of view, and make sure they provide something that benefits customers, users, or business stakeholders. On-site customers are in charge of priorities, so if they don’t think a story has value, they won’t include it in the plan.

Customer-centric stories aren’t necessarily valuable to the end user, but they should always be valuable from the perspective of on-site customers. For example, a story to produce a trade-show demo doesn’t help end users, but it helps your business sell the product.

Similarly, some stories will be too small for real customers to care about. For example, if you’re creating a credit card billing system, one of your stories might be, “Special handling for merchant decline code 54.” But on-site customers should know how each story contributes to the overall whole and be able to make prioritization trade-off decisions. (“We can postpone code 54 for now, but we absolutely must handle code 41, because that’s a fraud alert.”)

A good way to ensure that your stories are customer-centric is for on-site customers to write the stories themselves.

One practical result of customer-centric stories is that you won’t have stories for technical issues. There should be no “Design domain layer” story, for example—customers wouldn’t know how to prioritize it. Although developers can tell customers how to prioritize technical stories, that distracts the team from focusing on value and can leave on-site customers feeling disenfranchised.

Ally

Incremental Design

Instead, spread technical considerations across all stories. Rather than a single “Design domain layer” story, for example, incrementally modify the design of your domain layer with every story. This is easier if you use evolutionary design, which I discuss in the “Design” chapter.

Developers often struggle with making stories customer-centric. Keep practicing! Without customer-centric stories, on-site customers have trouble making good prioritization decisions, and ruthless prioritization is the secret to releasing sooner.

Ruthless prioritization is the secret to releasing sooner.

Developers, to make your stories customer-centric, talk them over with your on-site customers. Explain the outcome you’re trying to create and ask customers to write the story in their own words. If you need to, you can add a note to remind you of the technology the story relates to.

For example, if you think that the team needs to switch to another database technology, you could explain it this way: “We need to move our articles to a database that handles full-text search better. Searches already take over half a second, and it will keep getting worse as more articles are added.” A customer might write, “Stop article search performance from getting worse,” and you can add, “(full-text search database).”

Splitting and Combining Stories

Stories can be any size. When you first come up with an idea, your stories could be fairly large and vague: for example, an online store might have a “check-out page” story.

Ally

The Planning Game

To provide visibility and control, though, the team needs to finish multiple stories every week. During the planning game, you’ll split those big stories into smaller ones and combine small stories into bigger ones.

Combining stories is easy. Take several related stories, staple them together, and write your new estimate on the front, if you’re using estimates. In a virtual team room, cut and paste the story descriptions onto a single virtual card.

Splitting stories is more difficult, because they need to remain customer-centric. The trick is to find the essence of the story, not the individual steps it involves. What is the fundamental value the story provides, and what are the embellishments that build on that fundamental value? Write that fundamental essence as a story and each embellishment as an additional story.

If that’s hard to imagine, Mike Cohn has an excellent chapter on how to split stories in his book Agile Estimating and Planning. [Cohn2005] He provides the following options. (The examples are my own.)

• Split according to priorities. For example, the “check-out page” story could be split into “check out” (high priority), “coupons” (medium-high priority), “gift receipts” (medium-low priority), and “gift wrap” (low priority).

• Split along the boundaries of data supported by the story. For example, a story about collecting billing information could be split into “collect credit card info,” “collect gift card info,” and “collect PayPal info.”

• Split based on the operations that are performed within the story. For example, a story about processing credit card payment could be split into “collect credit card info,” “validate credit card info,” and “charge credit card.”

• Split into separate CRUD (Create, Read, Update, Delete) operations. For example, a story about administering customer data could be split into “add customer,” “view customer,” “edit customer,” and “delete customer,” as well as “list customers” and “sort customers.”

• Split out cross-cutting concerns (such as security, logging, and error handling) by making multiple versions of your stories. For example, a story about charging credit cards could be split into “charge credit card,” “log credit card charges,” and “handle credit card rejection.”

• Split out nonfunctional concerns (such as performance, stability, scalability, and so forth). For example, a story about charging credit cards could be split into “charge credit card” and “support 100–200 credit card transactions per minute.”

The best splits are the ones that allow you to prioritize stories separately and in any order. That takes practice and isn’t always possible, so don’t worry if you have trouble doing so.

Tiny stories

The more you split a story, the harder it can be to make it customer-centric. Don’t give up. If you can’t think of anything else, at least describe the technical work in business terms. This allows on-site customers to understand and remain in control of priorities. It also makes it easier to explain your plans and progress to others.

For example, if you have a story to “send an email when wire transfer completes,” programmers might say it involves the following tasks:

1. Register callback with banking service

2. Log webhook calls

3. Secure webhook

4. Parse webhook transaction data and query database

5. POST to transactional email service

Turn them into stories by restating them in business terms:

1. Tell bank to notify us when wire transfer completes

2. Log wire transfer notifications

3. Prevent forged wire transfer notifications

4. Look up customer associated with wire transfer notification

5. Send email to customer when wire transfer notification received

Again, it’s better to have stories that are independent of each other, but this is a good fallback option when you can’t figure out what else to do.

Special Stories

Most stories will add new capabilities to your software, but anything that requires the team’s time and isn’t part of their normal day-to-day work needs a story.

Documentation stories

Allies

Incremental Requirements

Incremental Design

Agile teams need very little documentation to do their work, due to their use of incremental requirements and evolutionary design, but you may need the team to produce documentation for other reasons. Typically, that documentation will be part of the work for a larger story, but you can also have documentation-specific stories.

Stories for creating documentation are just like any other: make them customer-centric and be sure you can identify specific completion criteria. An example of a documentation story is “tutorial for setting up billing.” See the “Documentation” section for more details.

Bug stories

Allies

No Bugs

Done Done

Ideally, your team will fix bugs as soon as it finds them, before declaring a story “done.” Nobody’s perfect, though, and you will miss some bugs. Track these bugs with stories such as “fix multiple-user editing bug.” Schedule them as soon as possible to keep your code clean and reduce your need for bug-tracking software.

Bug stories can be difficult to size. Often, the biggest timesink when debugging is figuring out what’s wrong, and you usually won’t know how long that will take until you’ve done it. Instead, put a timebox around it: “We’ll spend up to a day investigating this bug. If we haven’t fixed it by then, we’ll discuss it as a team and schedule another story.” On the card, write “timebox 1 day.”

“Nonfunctional” stories

Performance, scalability, and stability—nonfunctional requirements—should be scheduled with stories, too. Like all stories, they need a concrete, customer-valued goal. Unlike other stories, though, you’re likely to need developers to help define the goal. It’s not enough to say, “the software needs to be stable” or “the software needs to be fast.” You need to be able to describe exactly how stable or fast it should be.

When creating nonfunctional stories, think about acceptable performance—the minimum necessary for satisfactory results—and best possible performance—the point at which further optimization adds little value. You don’t have to write these numbers on the card, or necessarily decide on them right away, but it’s often useful to do so.

Why have two numbers? Nonfunctional requirements, particularly performance optimization, can consume an infinite amount of time. Sometimes you reach your “best” goal early: this tells you when to stop. Other times you struggle even to meet the “acceptable” goal: this tells you when to keep going. For example, the performance criteria for a web page might be, “support 500–1,000 requests per minute, with a latency of 50–200 ms.”

Like bug stories, nonfunctional stories can be difficult to size. You can use timeboxes for them, too.

Operation and security stories

Allies

Build for Operation

Whole Team

It’s not enough to build software for users. If it’s online, you have to build it to be monitored, managed, and secured as well. For example, you’ll need to be alerted when performance degrades, and you’ll need a way to conduct security audits and respond to breaches.

On-site customers often have trouble thinking of these sorts of stories, which is why it’s important that people with operations and security skills be part of the planning process. To help on-site customers understand their priority, discuss the stories in terms of the value they provide, not the technical work to be done.

Often, that value comes in the form of reduced risk. For example, a story to add distributed tracing could be described as, “Make it easier to find source of performance problems during performance emergencies (distributed tracing).”

Spike stories

The purpose of a spike story is to size another story.

Sometimes, developers won’t be able to size a story because they don’t know enough about the technology required to implement the story. When this happens, create a spike story to research that technology. The purpose of a spike story is to size the other story, not to design the solution or research every nook and cranny. For example, “figure out if ‘send HTML email’ story should be split.” Or, more concisely, “spike ‘send HTML email.’”

Ally

Spike Solutions

They’re called spike stories because you’ll often use a spike solution to do the research. But you don’t have to.

Clean-up stories

Ally

Slack

Agile teams are expected to work in a way that allows them to continue indefinitely, and this includes having enough slack in their schedule to constantly improve their codebase. If you use slack correctly, you shouldn’t need to explicitly schedule time for cleanup. The parts of the code you work on most often will automatically get cleaner over time. That said, sometimes you inherit crufty code, and it’s worth dedicating extra time to cleaning it up.

You shouldn’t need clean-up stories to keep your code clean.

Like any other story, clean-up stories need to be customer-centric. They must be entirely optional. You shouldn’t need clean-up stories to keep your code clean. You don’t ever want to be in a position where developers have to ask customers for permission to do necessary work, and you don’t want customers to have to ask developers for permission to ignore a story.

If you do make a clean-up story, speak in terms of the business benefit it provides. Often, that benefit is in the form of decreased development time. Crufty code is bug-prone and tends to take a lot of time to change safely. So, for example, instead of saying “refactor authentication service,” say “reduce likelihood of authentication bugs,” or “decrease time needed to make authentication changes.”

You probably won’t be able to quantify the improvement, but be prepared to provide examples that illustrate the benefit. Like this: “Know how we keep running into problems and delays whenever we change something related to login? This will solve that.”

Allies

Reflective Design

Refactoring

For clean-up stories that don’t have a clear stopping point, use a timebox. To make sure you can stop when your time is up, avoid rewriting code. Instead, incrementally refactor it, keeping the code working at all times.

Meetings and overhead

Don’t create stories for activities such as the planning game, all-hands meetings, and other organizational overhead. If you have an unusual time commitment, such as training or an off-site day, just expect to get fewer stories done that week.

Architecture, design, technical infrastructure

Allies

Incremental Design

Evolutionary System Architecture

Don’t create stories for technical details. Development tasks are part of the cost of implementing stories. Use evolutionary design and architecture to break large technical prerequisites into small pieces that you can implement incrementally.

Questions

Our customers understand development. Do we still have to write stories to be customer-centric?

It’s much more difficult to create customer-centric stories than developer-centric stories, so it’s tempting to find excuses to avoid them. “Our customers don’t mind if we have developer-centric stories” is one such excuse.

Your plan should be about value, and so should your stories.

Even if customers understand developer-centric stories, customer-centric stories lead to better plans. Your plan should be about value, and so should your stories.

If your customers are developers—if you’re developing software for developers, such as a library or framework—then your stories can use developer-centric language. Even so, they should reflect your customers’ perspective. Create stories about your customers’ needs, not your implementation details.

Shouldn’t developers make the software fast by default? Why do we need performance stories?

Nothing comes for free in software development. You don’t have to create performance stories, but you do need to know what “fast” means in your situation, and developers will need to spend time to make it happen. Splitting nonfunctional requirements into separate stories doesn’t change the amount of time required; it just gives you more insight and control over how that time is spent.

How do we make time for technical infrastructure and large refactorings, such as replacing a test framework?

Allies

Incremental Design

Reflective Design

Slack

Perform this sort of work incrementally, using evolutionary design and the slack in your team’s schedule. For large refactorings, you can also use clean-up stories, but working incrementally is usually better.

Prerequisites

Ally

Incremental Requirements

Stories are no replacement for requirements. You need another way of getting details, whether through on-site customers and incremental requirements (the Agile way) or a requirements document (the traditional way).

Indicators

When you use stories well:

• On-site customers understand all the work they approve and schedule.

• It’s easy to explain to stakeholders what the team is working on and why it matters.

• Your team works on small, manageable pieces and makes customer-valued progress multiple times per week.

• Stories are cheap to create and easy to discard.

Alternatives and Experiments

The main distinction between stories and the line items in most plans is that stories are customer-centric. If you can’t use customer-centric stories for some reason, customers cannot participate effectively in planning. This will eliminate one of Agile’s primary benefits: the ability to create better plans by blending insights from both customers and developers. You’ll also have trouble explaining progress to stakeholders. Unfortunately, no alternative practice will help.

Stories are a simple idea, but they’re also connected to a perennial software development problem: deciding what to build. Simple idea plus important problem means everybody has their own spin on stories. You can find any amount of templates and story writing advice online. All will claim to solve this problem or that so the team can build better software.

These experiments tend to miss the point. Stories are about the conversation, not the card. Any change that puts more focus on writing than talking—a template, more detail, a taxonomy of stories—is going in the wrong direction.

Similarly, stories aren’t how you decide what to build. They’re just a reminder. There are a lot of very good ways of understanding customer and business needs and turning that understanding into action. (I cover some of them in the “Visual Planning” practice.) Don’t use stories to create business understanding. Create business understanding first, make decisions, and use stories to remind you about those conversations and decisions.

Jeff Patton says stories are like a vacation photo: they remind you what happened. Because stories are just a reminder, they don’t need to be complicated. When you experiment with stories, think of ways of putting more emphasis on the conversation and less emphasis on the story, while still doing just enough to remind people what was discussed and decided. Make the vacation better, not the photo.

Finally, another common change is to track stories in a spreadsheet, or issue tracking tool, rather than on index cards. That can make lists of stories easier to read, but it makes visualizations and collaboration more difficult. It’s a net loss that’s hard to appreciate without experience. Give cards at least three months before trying alternatives. Even if your team is remote, use virtual index cards on your virtual whiteboard rather than a spreadsheet or issue tracking tool.