In my user stories book and in all my training and conference sessions on user stories I advocate writing user stories in the form of “As a <type of user>, I want <some goal> so that <some reason>.” While I consider the so-that clause optional, I really like this template.
At a recent conference, someone asked me why. Because I get that question fairly often I want to give three reasons why here:
Reason 1
Something significant and I’m tempted to say magical happens when requirements are put in the first person. Obviously by saying “As a such-and-such, I want….” you can see how the person’s mind goes instantly to imagining he or she is a such-and-such. As for the magic, Paul McCartney was interviewed and asked about why the Beatles songs were so amazingly popular. One of his responses was that their songs were among the first to use a lot of pronouns. Think about it: She Loves You, I Wanna Hold Your Hand, I Saw Her Standing There, I Am The Walrus, Baby You Can Drive My Car, etc. His point was that these helped people more closely identify with the songs. I tried briefly to find a source for this interview tonight and the closest I found was this. The information in that reference fits my recollection of hearing McCartney says this during a radio interview in 1973 or 74 that I assume was recorded when the Beatles were together.
Reason Two
Having a structure to the stories actually helps the product owner prioritize. If the product backlog is a jumble of things like Fix exception handing, Let users make reservations, Users want to see photos, Show room size options, and so on, the product owner has to work harder to understand what the feature is, who benefits from it, and what the value of it is.
Reason Three
I’ve heard an argument that writing stories with this template actually suppresses the information content of the story because there is so much boilerplate in the text. If you find that true then correct it in how you present the story. I’ve seen backlogs in Word that present the boilerplate in grayed text with the unique parts in black. I’ve created product backlogs in Excel that use column headings to filter out the common text. Look and you’ll see what I mean:
Seriously take a look at the image above before continuing….I’ll wait……Please, really look at it before reading further…..
OK, here’s how I bet you read the spreadsheet. I bet that as you read most of the rows you added in the “As a…”, “I want….” and “so that….” text, possibly even by looking at the heading as you read across each row. I’ve experimented by asking people and this is what most people do. If that text is unnecessary, why do we mentally mouth the words to ourselves or even glance at the heading while reading the row? Perhaps it’s not so non-essential after all.
For now, and probably a long time to come, I’ll be sticking with the “As a <type of user>, I want <some goal> so that <some reason>” template for these and other reasons.
Hi Rusty–
Thanks for sharing your story. As much as part of me hates having templates for things, the “As a type of user, I want some goal so that some reason” template really helps.
[...] savaged @ 15:42 Behavioural Driven Development (BDD) is exciting to me. That’s becasue the Agile User-Story and Acceptance Criteria, actually become merged with the code-base itself. Bringing them to life, [...]
[...] Mike Cohn on user story writing http://blog.mountaingoatsoftware.com/advantages-of-the-as-a-user-i-want-user-story-template [...]
another column to hold ‘Confirmation’ to this template would have been very nice. I use this template and have added ‘Confirmation’ column to list ‘Sucess’ or ‘Fail’ conditions to satisfy the story
@ Mike Cohn
It is really impressive that you take the time to answer almost every question in the comments! Thank you. Big fan of your work.
Thanks, Sergio. I appreciate that. I really try to answer all the questions here.
[...] o padrão de stories sugerido por Mike Cohn (e também encorajado pelo próprio Dan North), nosso cenário poderia ser algo como: Title [...]
Hi Mike!
You wrote “While I consider the so-that clause optional”.
I totally disagree with that. Actually, I consider the “so-that” clause the most important part of a story, because this is the VALUE!
Why keeping a story on the backlog, if there is no value on it???
Great article man!
Cheers
Hi Nicolas–
I say that the so-that clause is optional for two reasons:
So, I usually offer the guideline that a good product backlog will be about 90% user stories and about 90% of those will have good, clear so-that clauses. (Since I’ll get asked: the 10% of the backlog that isn’t user stories is just stuff someone put on the product backlog that probably could be turned into a true user story but wasn’t worth it. For example, “Upgrade developer laptops to Windows 7″ would not bother me on a product backlog today but we certainly could use the template to write that if we wanted.)
Mike,
Highly informative blog to go through…
I am wondering how we can depict the dependencies/linkages between User Stories. Do you recommend having a kind of ‘Story Architecture’ before we start breaking down a requirement?
Hi Seetharamu–
The best thing is to leave the stories as large epics as long as possible. This keeps most dependencies within a single epic and so they aren’t a problem.
Other dependencies can exist and you can handle those by annotating the card the story is written on. I don’t bother annotating “natural dependencies”—if we assume that we will add widgets to the database before deleting them, I don’t annotate the delete story with “assumes adding widgets is done first.” Sometimes that natural assumption will be false but in probably 99% of all cases that just means some of the effort estimate moves directly from one story to the other.
As for a “story architecture” the way I think about this is really just as a Feature Breakdown Structure (epics at the top, smaller features below). Sometimes a mindmap is useful and there are good tools for this. Jeff Patton calls a similar approach a story map but he brings time into his maps. You may want to look at those. Personally, I leave time out in the early stages because it’s impossible to prioritize (correctly) without knowing the cost and when I’m writing stories I don’t yet know the cost of each.
[...] refined the template I use for writing user stories. I am still inspired by Mike Cohn and I used his template for user stories as a base for my own [...]
[...] and in the process usually teach Planning Poker. Planning Poker is a tool. The story template [ref] designed by Mike Cohn is a tool. Likewise, a talking stick in a stand up meeting, a timeline in [...]
[...] Langage Naturel… « Alors déjà Vincent, nous, franchement, quand on relit nos tests, on reconnait plus certaines choses… C’est quoi tous ces mots clés qui apparaissent dans nos tests après le passage des développeurs? Ca devient illisible! » Sandie AMOA. Et si, messieurs dames de l’AMOA, vous utilisiez le langage naturel? Si, chaque action de votre scénario de recette était une jolie phrase en français, sans tableau? Et si, vous aviez juste à utiliser ce formalisme simple (décrit par ailleurs par « M. SCRUM » ici): [...]
[...] month and what needs to be done that day to succeed per the defined goal. As Mike Cohn writes (http://blog.mountaingoatsoftware.com/advantages-of-the-as-a-user-i-want-user-story-template) a user story in Agile Software Development is often in the form of “As a <type of user>, I [...]
Mike,
Please can you give me the value behind epics and would you ue them as almost phases when you thing of PMBOK.
Epics are value because they support the idea of progressive refinement of the product backlog. Rather than investing in writing a fully detailed product backlog upfront, we write each part of the product backlog at the level of detail most appropriate. If we’re going to work on a part of the system soon, we write small stories. If we’re not going to work on it for awhile, we write epics.
We started with the “As a ___, I want to _____, so that I can _____” format for our stories. But after a while we realized that we were writing stories which didn’t emphasize the business value we wanted to deliver.
So now we’ve switched to “So that I can _______, as a ______, I want to _____” format where we now emphasize the business value over the specifics of what we want to do.
Mike,
Some of my clients have run into trouble when using this template, especially when the is really an internal stakeholder of some sort. In your User Stories book, you mention that a user story is valuable to a user OR purchaser of system. Does it extend, then, that you can represent a “purchaser” in the formalized story template?
Scenario: You work at a company that has a website that sells products. Someone in marketing wants to display an ad for a complimentary product every time a user puts certain products in their cart. You could write this where the “type of user” is the shopping user, but really, the person who wants the functionality is marketing. So, is something like this valid? Note that I’m extending the “purchaser” label to someone in marketing.
As the director of marketing, I want to suggest complimentary products(if they exist) when users put certain products in their cart, so that we can increase sales.
Scenario 2: You work at a company that has a website that sells products. Your website uses outside Company A to process payments. Someone in the finance department has decided that using Company B would be better, because processing costs are lower and the other system is easier to use when processing refunds. You could write this where the “type of user” is the shopping user, but really, the person who wants the functionality is the finance department. So, is something like this valid? Note that I’m extending the “purchaser” label to someone in finance.
As the finance channel manager, I want our site to use Company B to process payments so that we save money on transaction and refund(customer service) costs.
Obviously in the conversation and acceptance tests, the team would discuss how this impacts the end user, and would write acceptance tests that cover the end user/system interactions.
Is going down this road ok, or fraught with danger?
Hi Charles–
I see nothing wrong with these stories. This is where the use case term “actor” is better. A good user story can be about any stakeholder of the system. And the story can just as easily be something other than “want” as in “As a shopper, I am shown complementary products when I start to check out.” Or, “As a user, I am forced to change my password every 90 days.” So not all stories need “want” in them.
I see no danger ahead with stories as you’ve described them above.
Thanks for the feedback, it is great to hear it from the horse’s mouth.
I’ve been on a tear lately trying to advocate to people that really, the “As a , I want , so that ” is not in and of itself a User Story. It is a “description” of a User Story, and using the template is just *one* technique to represent the description.
People focus so much effort on the description and too little on the acceptance tests and conversation(the other 2 components of a US), and really, it should be the opposite, IMO.
Having said that, my experiences as a Scrum Coach may be skewed since I deal with teams that are mostly brand new to User Stories and Scrum. The good fight continues!
I’ll only make one other *very* minor comment. When you re-wrote the complementary products description, we lost some information. Both the primary stakeholder (marketing), and the for the story were lost(much of the benefit provided by the template, btw). That may be important, or it may *not* be that important, but I felt it was worth noting. Again, using the template is just *one* way to represent the US description.
Correction:
> Both the primary stakeholder (marketing), and the for the story
should read:
Both the primary stakeholder (marketing), and the *reason* for the story
I gotta say, Mike, looking at your website, and especially this page:
http://www.mountaingoatsoftware.com/topics/user-stories
It seems like you also put a lot of emphasis on the description and almost no emphasis on the acceptance tests (aka COS). That seems *very* unfortunate to me.
In fairness, you do put good emphasis on the conversation, though. Why doe COS get no love on your User Stories home page?
Fair point. I will rectify that when I have time. (It won’t be any time soon, though.)
Hello Mike,
We are struggling at our company because we have been calling using the term “stories” to represent engineering work. We are using a tool now that references Stories and Tasks. There is a lot of discussion surrounding the definition and use of these two work items. When should we use a story to describe our work and when should we use a task.
Do you have any opinion on this?
- Bruce
Hi Bruce–
I love it when tools force our vocabulary. (Not really.)
Generally, user stories are used on the product backlog. During sprint or iteration planning user stories are discussed and turned into a set of tasks that make up the sprint (iteration) backlog.
Another distinction is that a task is generally done by one person whereas a user story needs multiple people. That distinction works in almost all cases–”as a patient, I would like to search for a doctor so that I can find the right one for me” is a good user story and needs programming, testing, UI design, database work, etc. “Create the database” would be a good task within that story. The time when this distinction (one person / multiple) doesn’t work is for a task like “Meet to discuss user feedback on UI design.” That’s a task: It’s one thing–a meeting. But it involves multiple people.
Mike, there is a serious flaw here… everyone knows that the Beatles broke up in 1970!
Hi Simon–
Yes, they did. I heard the radio interview in 1973 or 1974 but what I said above was that I think it might have been recorded when they where together (prior to that).
BTW: In 1980 there were lots of rumors swirling that they would reunite. This was because they had almost done so on a Saturday Night Live episode. I remember having a tee shirt that said “Beatles Reunion Tour 1980–I was there. They weren’t.” I loved that.
Great post. One benefit of the ‘As a’ section that I don’t hear very often is that it provides a starting point for planning security – something that too often is saved until last. In many (but not all) cases, there may even be a 1:1 ratio between ‘As a’ user types and security groups, database roles, etc. In the example above, I now know that we’ll probably need to provide roles for ‘estimator’ and ‘moderator’.
Good point, Daniel.
HI Mike, Great article. Plus, your responses to each of the comments have turned it into a great resource on internet. What’s your take on including “Non-functional” requirements in the user story? Is that advisable?
Thanks, Divik. For information on non-functional requirements see this blog post: Non-Functional Requirements as User Stories.
Hi Mike, I am fairly new to any agile techniques but I am involved in a large project using scrum where the backlog items read something like ‘Produce an application that processes data from a set of sensors’. This might require reading data from multiple sensor types, validating the data, transforming the data (some of which requires complex algorithms), publishing the data using some pub/sub framework, alert the user of any exceptions. The final app almost always involves some very tight performance requirements which end up needing us to write (and test) multi-threaded code. In general, we are usually only given an interface spec for the inputs and outputs and have to ask lots of questions in order to determine the real required functionality and even then we end up making our best guess at what processing is required. Somehow I get the feeling that this is not really what agile/scrum is all about and that until the PBI is as complete and accurate as can be then we are on a hiding to nothing!! I don’t believe that a user story stating ‘as a user I want a complete sensor processing app to process/transform/validate/publish/notify data’ is the correct level of decomposition. Any thoughts?
Hi Stuart-
Yes, you’re definitely going to want to break those into smaller stories from what I can tell from this distance. Those sound like large stories (which we call “epics”). Those are fine as placeholders way into the future. But when it’s time to work on them, the stories need to be small enough that each can easily be done inside of a singe sprint/iteration.
At the company where I work, we don’t actually “do agile”, more typically we use waterfall, however for a project that’s just started, as lead business/systems analyst here’s the approach I’m leading the project team through.We’ve had a couple of ‘face to face workshops involving business stakeholders and IT:
1. Firstly, we started off with a context diagram (highest level data flow diagram) which shows the system under design (SUD) as a “black box”. On the context diagram we then identified all of the actors (people/roles and systems) that need to interact with the SUD.
2. For each actor we identified high level goals in Verb-Noun format. eg. ‘Make a Payment’, ‘Submit a Claim’ etc
I almost always start off with these two steps for every project as it helps to “set the scene” and assists with high level scope.
Now, normally at this point we would then dive into elaborating Use Cases, and associated functional and non-functional requirements however instead, this time around we are trying out capturing User Stories in the “AS A x I WANT y SO THAT z” format. ie. We are applying that by examining each Actor that was identified and looking at the high level goals (from step 2) as well as asking “what else does this actor want” using the suggested User story template.
We’re using a simple spreadsheet to rapidly capture the User Stories with the “AS A”, “I WANT”, “SO THAT” captured across three columns.
The feedback has been great….the business finds it easy to express requirements in this manner. Also, the value that the “SO THAT” portion has provided for each story
has proved very insightful for the business. We were able to eliminate certain ‘features’ the business thought they wanted but as it turned were not really necessary (by virtue of the business stakeholders not being able to clearly articulate this portion of the User Story.)
Anyway, the main point I wanted to make here is that despite not following an agile methodology, there is still great value is using User Stories with more traditional approaches such as waterfall.
Adam
Hi Adam–
Thanks for the story. You’re absolutely right that user stories are more broadly applicable than pure agile projects.
User story driven development to address non functional requirements like scalability, performance, testability, and maintainability for the system has always been a challenge. It’s very difficult to show value to user in it and they always get prioritized low for first little iteration. These cross-cutting concerns need to be architected and designed from day 1 into the system otherwise it is leads to design re-work. Do we have models, case-studies, experience to share on this?
Hi Tribhuwan–
I tend to shy away from statements like “These…need to be architected and designed from day 1…” because even a single counter-examples disproves the “need to be.” I will go so far as to say that many systems benefit from some amount of upfront consideration of these non-functional requirements. You’ll find a lot more on that subject on this blog–for example, see posts on balancing anticipation and adaptation, writing non-functional requirements as user stories, and on design being both intentional and emergent.
There is also, of course, a great deal more in the Succeeding with Agile book.
Hi Mike, great post. I have implemented this approach as a preliminary step before diving into wireframe design for the development of our mobile website. It is a great requirement gathering tool that can be shared across the organization.
Just one question. After we have gathered a list of Stories, should we create Epics based on user types or macro functionality?
Best,
Robert
Hi Robert–
I’m glad you liked the post.
Once you’ve gathered a set of stories, I’m not sure what additional epics you’re thinking of creating. (“Epic” = big user story.) If you’ve got user stories (probably some small and some epics), I would work from that list. I wouldn’t deliberately try to turn smaller stories into epics. I may be missing your true question.
Hello Mike,
Love your work!
I just want to make sure I am understanding this before I proceed at work. It has to do with implementing User Stories into Scrum.
I have developed a 3-column template, great idea, and am starting to gather User Stories/Epics. If I understand this right I can use these stories as actual items in my Product Backlog? The story board in essence becomes my Product Backlog?
From there we will eventually need to break the Epics into shorter stories but that just adds to the Product Backlog.
We then use the stories and transform them into workable tasks for the Sprint Backlog, right?
Sorry if I am using improper terminology, I am new to this.
Thanks, Michael. I’m glad you like what I’ve done.
I think you’ve summarized it all perfectly. User stories become the items on your product backlog–and yes, the product backlog will have epics and regular stories on it. If you put up a story board that becomes your product backlog. Many teams will also put their sprint backlog on the wall—organized in rows with columns like “to do”, “in process” and “done.”
I think you’ve got all the terms down perfectly. Good luck!
Actually I find the format: “in order to [get some value] I, as [a certain type of user], would like [some functionality].” much more useful and it focuses on the WHY part which is the part where most organisations I have coached have had problems and benefitted from improvements.
Hi Hass–
Thanks for sharing that. Our experiences have been completely different. Teams I’ve worked with have found that format forced–no one talks like that. So it may work fine among technologists but seems very contrived when working with real users or customers. But, the important thing is to have a variety of ways to try as no one solution will be right for all teams.
Hi Mike,
I have a question or comment regarding the format of user stories, especially the acceptance criteria. I often feel the context is missing when the typical user story format is used.
I found this resource, http://dannorth.net/whats-in-a-story/ – and it uses the typical user story format, as discussed here, but adds to it a context, which could be described as acceptance critera in more details
..eg. as a user I want so that…GIVEN, WHEN, THEN..
example from the web site I mention (I only copied one scenario).
“START”
Story: Account Holder withdraws cash
As an Account Holder
I want to withdraw cash from an ATM
So that I can get money when the bank is closed
Scenario 1: Account has sufficient funds
Given the account balance is \$100
And the card is valid
And the machine contains enough money
When the Account Holder requests \$20
Then the ATM should dispense \$20
And the account balance should be \$80
And the card should be returned
“END”
What are your thougths on this? I assume this has been discussed somewhere in details?
thanks,
Hreinn
Hi Hreinn–
I’m not a fan of that format. It doesn’t feel natural. Sure it fits all those tests into one “sentence” but it’s hardly a story. It might as well be an IEEE 830 spec. It seems to miss that the written part of a story is to lead to a conversation. That’s where those details come out. I advocate capturing them as tests or notes on the back of a story card.
Hi Mike! I’ve enjoyed reading all the comments and especially your response. I am also a fan of the User Story Template because I think it helps to truly identify your goal. How do you feel about adding this ‘User Story’ as the scope of a Use Case? I am working on an Agile project where this format describes the User Goal best but we also need additional information that a Use Case format would supply.
Thanks!
Hi Lianne-
I’m glad you find this blog enjoyable. Some teams will mix user stories and use cases. They’ll write high-level user stories (epics) and use a use case to document the story in more detail, for example. So while I see things like this occasionally, almost all of the companies I’ve seen do this have eventually moved away entirely from their use cases and to just user stories. Similarly in my classes, I hear much, much less discussion about use cases today than, for example, five years ago. Oddly, though, use cases have come up in a ScrumMaster class today and in some client work earlier in the week.