The short short story: How long does it have to be?
Scrum teams often use user stories for backlog items. Unfortunately, one of the most important aspects of a story—its extremely short length—has been subtly transformed over time, and stories have lost their original essence and potency.
Story writing is usually taught now as a singsong "As a I want so that ." The writer should then immediately document acceptance criteria in the form of a constraint list or automated acceptance tests. Many consider it poor form to create a story that someone outside the team (say, a senior manager stakeholder) can't understand from its documentation alone.
I'll make the case here that an ideal story's documentation should be nothing more than a short, memory-jarring name—what Robert Martin calls a "mnemonic token."
The storied past
Ward Cunningham first described user stories in 1995, in his "Episodes" pattern language. The pattern is named Implied Requirements:
Development commitments generally obligate developers to meet some customer need in a timely and satisfactory way. The tension here is to define a need in sufficient detail that commitments have meaning without exhausting upfront analysis or overconstraining a solution. Therefore: Select and name chunks of functionality. Use names that would have meaning to customers and be consistent with the product initiative. Allow these names to imply customer requirements without actually enumerating requirements in the traditional sense.
He gives examples such as "high-quality printing" and "settlement date positions." In the related "Work Queue" (backlog) pattern, it becines clear that there is nothing more than implication in an Implied Requirement: They are "really just names" and the "deliverables may be ill-defined, being represented more by a vision or desire than by anything concrete or measurable."
Not many use the term "implied requirement" now, with a few exceptions such as Jim Coplien and Neil Harrison in their *Organizational Patterns of Agile Software Development*, which reproduces Cunningham's pattern. "User story" is the more sonorous name the industry has adopted for the Implied Requirements pattern. But before the now-familiar predicate came into vogue, when the concept first began garnering attention by virtue of inclusion in the Extreme Programming corpus, it was known simply as a "story."
Tell me a story
The term *story* first surfaced in 1999 with Kent Beck's *Extreme Programming Explained*; the definition in the glossary is "one thing the customer wants the system to do." The Planning Strategy chapter explains that a story is written on an index card "with a name and a short paragraph describing the purpose of the story."
The amount of story documentation described in *XP Explained* exceeds the "just name" length given in the Implied Requirement pattern. However, in the *Planning Extreme Programming* book released the following year, Beck reduces the story length and falls back into alignment with the minimal approach. He also begins to use the now-familiar term *user story*.
Are you gonna *use* that?
In *Planning Extreme Programming*, Beck and Martin Fowler return to the "conceptual" definition of the newly named user story, explaining that you elaborate details when you build the stories, not when you write them:
The shorter the story, the better. The story represents a concept and is not a detailed specification. *A user story is nothing more than an agreement that the customer and developers will talk together about a feature.* Hideous written detail is not necessary if the customer can work with the programmers while they are programming. . . . It's not that you don't need all of those details. You just don't need them all up front. When you need to build the stories, then you need more details. But whatever you do to make the story more detailed, do it when you need the details.
Mike Cohn echoes this sentiment in *User Stories Applied*: "Rather than writing all these details as stories, the better approach is for the development team and the customer to discuss these details. That is, have a conversation about the details at the point when the details become important."
When teams defer documenting the details, they reduce the potential for waste and thereby reduce the cost to build software. If the priority of a story is decreased to the point that it's never built, the effort spent creating and maintaining the story artifact is considered waste. As David Anderson makes clear in his dense and thorough *Agile Management for Software Engineering*: "In order to maximize the production rate, waste from changes must be minimized."
Haven't you got something better to do?
Another consequence of minimally documented stories is time saved that would otherwise be spent writing. It takes time and effort to write "just" a paragraph of description and "just" a list of acceptance criteria for each story. The product owner has plenty of other work to do—market research, customer collaboration, competitive analysis, product feature innovation, release planning, acceptance testing, manager meetings, and so on. Is documenting a story really the best use of valuable time?
Furthermore, excessive documentation engenders a kind of cognitive burden: The writer feels disinclined to "waste" the effort already spent documenting a story by rewriting it or reprioritizing it in response to changing needs:
The user story practice enables flexibility because a small fraction of time is originally invested to create user stories for the backlog. The team is then free to reprioritize them in response to new information or changes in the environment without wasting much work in progress. . . . Consequently, the product utility is improved and the cost to build the software is reduced.
Accentuate the evocative
With such a small amount of documentation—just a name—how will folks come to know the story details? The minimalist story acts as what Amr Elssamadisy calls an evocative document: It "evokes the memories, conversations, and situations of those who wrote the document." A team using the evocative document pattern
spends more time in face-to-face conversation and less time building and maintaining documents. The documents they keep tend to be simple and only comprehensible to those in the conversation; therefore, to transfer the knowledge behind the document to someone who was not there, the conversation and context have to be repeated and the document built from scratch. What is gained by this is a much better transfer of knowledge within context that ultimately leads to more proper understanding of the application and reduced maintenance costs.
The lack of detail in a minimalist story acts as a *forcing function* that fosters Agility through increased communication: "To encourage conversations, write down just enough information to remind you and others what the subject is. For those who have not participated in a conversation on the topic, the text will not have much value and will thus prompt them to find the right person to talk to."
Now why didn't *I* think of that?
Because the product owner does not commit to written detail in a right-sized story artifact, the team is free to creatively develop the feature with fewer preconceived constraints. Innovation is intrinsically encouraged. The lack of explicit specification creates a vacuum that the entire team must fill: It fosters a team-wide synergy that results in a realization of the feature that is richer and more creative.
The short short story takes a "just-in-time commitment" approach. Mary Poppendieck explains the value of this in *Implementing Lean Software Development*: "As we guide our product development process, we need to recognize that developing a product is all about learning, and the longer we defer decisions, the more we can learn."
A principled stand
The ability to perform real-time adjustments in response to change requires an infrastructure that supports continuous refactoring as teams elaborate and modify features. There are engineering patterns that Agile teams typically use to ensure that the software being developed is sufficiently malleable and stable to withstand continuous change, such as test-driven development, refactoring, automated acceptance testing, and continuous integration. Social patterns such as pairing, whole team together, and collective code ownership help create an environment that spreads knowledge of the product across the entire team, fostering the synergy, creativity, and courage necessary to shape the software dynamically.
In and of themselves, short and sweet stories directly align with, support, and encourage many of the Agile Manifesto Principles:
• Trust and enable
• Collaborate daily
• Hold face-to-face conversations
• Welcome changing requirements
Testing, testing, 1 . . . 2 . . . 3 . . .
So, if a story does not contain documented details prior to working on it, and evocative documentation is sufficient to engender a shared understanding among team members, do we ever need to record the specific details of a story in persistent form? Yes: When work begins on a story, we record the details in the form of automated acceptance tests.
The automated acceptance test pattern is a safety net that prevents waste of loose conversational specification "setup time." At the appropriate time, the team commits details to automated tests that are objectively verifiable and capture the requirements as *executable* specifications. The tests act as regression protection, holding a team's memory of the story details in a "permanently accurate" form (if the tests are executed regularly). A good automated acceptance test framework encodes the specifications in domain-specific language so anyone familiar with the business domain can read and write them.
The long and the short of it
An ideal user story is short:
• Just a name
• An evocative document
• Creatively elaborated when work begins
• Detailed as automated acceptance tests
1. Robert Martin and Micah Martin, *Agile Principles, Patterns, and Practices in C#* (Englewood Cliffs: Prentice Hall, 2007), 14.
2. Ward Cunningham, "EPISODES: A Pattern Language of Competitive Development," in *Pattern Languages of Program Design 2*, ed. Vlissides, Coplien, Kerth (Reading, MA: Addison-Wesley, 1995), 375–6.
3. Ibid., 377.
4. James Coplien and Neil Harrison, *Organizational Patterns of Agile Software Development* (Upper Saddle River: Pearson Prentice Hall, 2005).
5. Kent Beck, *Extreme Programming Explained: Embrace Change* (Boston: Addison-Wesley, 1999), 179.
6. Ibid., 90.
7. Kent Beck and Martin Fowler, *Planning Extreme Programming* (Boston: Addison-Wesley, 2001), 46–7.
8. Mike Cohn, *User Stories Applied: For Agile Software Development* (Boston: Addison-Wesley, 2004), 6–7.
9. David Anderson, *Agile Management for Software Engineering: Applying the Theory of Constraints for Business Results* (Upper Saddle River: Prentice Hall Professional Technical Reference, 2004), 101.
10. Elssamadisy, *Agile Adoption Patterns* (Reading: Addison-Wesley Professional, 2008), 149.
11. Ibid., 143.
12. Ibid., 145.
13. Ibid., 151.
14. Mary Poppendieck and Tom Poppendieck, *Implementing Lean Software Development: From Concept to Cash* (Boston: Addison-Wesley, 2007).