Creating User Stories

The 5 W’s of an Issue

When an issue gets raised in a production environment, a project planning meeting, or a requirements-gathering meeting, we ask the Who, What, When, Where, and Why of the issue to figure out how to solve it.

Typically, the Where is implied as “In the System” and the When is either “Yesterday”, “ASAP”, or “We’ll figure that out once we know the size, scope and schedule for the issue/project.”

That leaves us with the Who, What, and Why. These three questions are at the heart of a User Story.

User Stories

A User Story is a simple statement that answers the questions Who, What and Why of any given issue.

For example:

“As a night owl, I need coffee in the morning so that I can function properly.”

“As a fire station janitor, I need to get a text message whenever the truck rolls out so that I can go over to clean the station when the firefighters are not there.”

“As an accounting user, I need the system to calculate the tax for an order based on the City, County, State and Country selected in the “Bill To” address so that the tax amount is correct for each customer and to reduce billing errors.”

“As a security admin, I need to be able to lock people out of the system so that we can do an update at 1 AM Sunday morning.”

“As a manager, I need to see the Sales by Region on a map so that I can visualize the sales by region and determine which regions are most in need of sales support staff.”

In each of these examples, you can see that the User Story takes the form of a single statement that follows this template:

In short: “Who needs What and Why.”

More specifically:  “As a type of user, the system should have some feature/do some action so that some benefit will be received.”

What Not to Do

User Stories should not be ambiguous.  For example, “As a user, I need the system to report on sales, so that I can analyze sales,” is not specific at all.

Nor should they be technical: “As a Data Entry operator, when I click the Add button it should create a new CUST_TBL row and default the ADDRESS_1 field to the ADDRESS_ID of the ADDR_TBL record that has DEF_ADDRESS set to 1 so that the CUST_TBL defaults correctly.”

Nor should they omit any of the three parts of the statement.  “The system should apply shipping charges to each order so that the shipping charges are correct,” is not as useful as:  “As a customer, I need the system to show me the shipping charges that apply to my order so that I can know what they will be before I submit the order.”

It is especially tempting to leave off the third part, the “Why?” However, it is a fundamental component of the User Story.  Notice the very different implications of “As a security admin, I need to be able to lock people out of the system so that we can prevent ex-employees from logging in.” and “As a security admin, I need to be able to lock people out of the system so that we can do an update at 1 AM Sunday morning.”


User Stories answer the Who, What, and Why of an issue.

User Stories take the form: “As a type of user, the system should have some feature/do some action so that some benefit will be received .”

The 3 Things a Project Needs to Accomplish – Highest Level Requirements Document for an Agile Project

Often, in an agile software development project, there can be a “fly by the seat of your pants” feel to the development effort as stories are created, prioritized and scheduled into Sprints without a formal Requirements Phase or a 10 pound Requirements Book – especially if you are working in an almost-Agile or mostly-Agilish environment.  One way to handle the lack of a Requirements Book, is to create a “3 Things My Agile Project Needs to Accomplish” document.

The “3 Things My Agile Project Needs to Accomplish” document is lightweight, and should typically be a single page.  It simply lists the 3-5 things your project needs to accomplish, with 3-5 bulleted items below each of the things breaking the “Thing” down into high level, one sentence descriptions of functionality that will accomplish the “Thing”.

Here’s an example template:

My Agile Project

Project Purpose in 1-2 sentences.

1.    First (Most Important) Thing the Project Needs to Accomplish

  • High level functionality that will accomplish the first thing
  • More High level Functionality
  • More High level Functionality
  • Perhaps More High level Functionality
  • Perhaps More High level Functionality (Max 5 items. If you need more, then you probably need another thing to accomplish or you aren’t thinking big enough.)

2.    Second Thing the Project Needs to Accomplish

  • High level functionality that will accomplish the second thing
  • More High level Functionality
  • More High level Functionality

3.    Third (Least Important) Thing the Project Needs to Accomplish

  • High level functionality that will accomplish the second thing
  • More High level Functionality
  • More High level Functionality



You may need up to 5 things the project needs to accomplish.  Any more than that and either, you aren’t thinking big enough, or the project has a very broad scope and should likely be broken down into smaller projects.

The bulleted items represent business objectives.  At this level, you should definitely be thinking in terms of “What does the solution need to do to accomplish one of the 3 things?”  “What?” implies using business objectives and business nomenclature.  We should not be concerned with “How the solution needs to work or how the solution needs to be built.”  Also, the bulleted items are not User Stories, or even Features, in and of themselves.  They are bullets of business functionality that describe “What?” is needed.

On index cards or in an ALM tool like MS TFS, each bulleted item can be translated into one or more (usually not more than 3-5) Features.  (If you need more than 5 features, you should probably go back to the 3 things and add another bullet, or even add an additional thing.)  These features should be written using business nomenclature and are still “What needs to be done?”, rather than “How?”

Each Feature, can then be elaborated into User Stories and Test Cases.  The process of making this happen usually occurs in a meeting with the developers, testers, SME’s and project/team leader (e.g. ScrumMaster or PM).

Traditionally, the User Story should be in the format:

Casual:  As a <type of user>, I want <some goal> so that <some reason>.

More Formal:  As a    Concerned Party   , I want    goal or business or technical feature or function (remember What, not How)   , so that    reason/business purpose/justification   . 

Using notecards, the User Story is written on the front of the card, and 3-5 Test Cases that will prove that the feature or function works are on the back.  The combination of the User Story and Test Cases should be sufficient to qualify as “Requirements”.  It should be possible for the team to elaborate the Tasks needed and estimate the Story Points (for the Stories) and Hours (for the Tasks).

For example, here is a User Story:

As an Analyst, I want a Widget Month Pricing table that includes one record for each Widget for each month that that Widget was on sale, including a blank Market Price field, so that I can store the Market Price generated by the Pricing Algorithm for each Widget/Month combination.

And here are some Test Cases:

  • Does the table show only relevant records based on Month and Widget?
  • Can the Pricing Algorithm, and only the Pricing Algorithm, write to the Market Price field?
  • Does the table show the right Widget/Month records for all Widgets?
  • Does the hourly refresh of the table run in under 90 seconds?

The User Story and Test Cases above give me the info I need to be able to estimate the story (in Story Points), task it out and start working on it.

A note about the Test Cases and Non-functional Requirements (NFR’s).  NFR’s, like security requirements and performance requirements, are not well suited to User Stories.  But they work very well as Test Cases.  As shown above, the User Story made no mention of the hourly refresh, but this requirement came out in the discussion of the story and was captured as a Test Case.  Also note the inclusion of the performance requirement for the hourly refresh.  Both the assumption that there would be an hourly refresh and the performance requirement that it not take more than 90 seconds are NFR’s that should be captured while the Story is being elaborated.

An Introduction to Estimating with Story Points

In the agile process, when we speak of estimating, we refer to Points (often called Story Points).  This article explains Points and how we use them in the estimating process.

First, let’s take a peek into a typical Project Manager (PM) – Developer conversation (maybe you’ve had a conversation like this yourself):

PM:  So, how long do you think it will take to finish this project?

Developer:  Oh, I don’t know, 2-3 weeks, maybe 4.

PM:  Well, how about this User Story; how long will that take?

Developer:  I’m not sure, but I would guess I can get that done in a couple of days, maybe three, or four.

Some things to note about this conversation:  In the first estimate, the Developer gives a range of 100% (2 weeks) to 150% (3 weeks) and then extends it to 200%.  What do you think the PM heard?  Let’s be kind, maybe he heard six weeks, which extends it to 300%.   A similar thing happens with the second estimate, but it’s smaller in scope so this time the range is from 100% (3 days) to 133% (4 days) to 167% when the PM adds a one day buffer to that estimate as well.

Clearly, there is something wrong with the estimating abilities shown in this scenario.  Note that this is not necessarily a reflection of the estimator’s inability to estimate well, but rather of the situation.

What’s wrong is that no one trusts the estimates because they are invariably wrong.

What if your estimates could be reliable and useful?  What factors would we consider?

First, there is the size of the problem in a perfect world; this is typically where the “2-3 weeks” estimate comes from.  Second, there’s the “unless something goes wrong”, which caused the developer to say, “…maybe 4.”  What goes into the “unless something goes wrong” check?  It is a consideration of risk and complexity and prior knowledge.  Let me explain, if the User Story under consideration has a high degree of risk, or is quite complex to implement, or if the developer doesn’t yet know how to use the technology that this User Story asks for, then the estimate goes up and becomes more approximate.  Finally, there’s the elapsed time: a simple table change may take the developer 20 minutes to design and document, but then it takes a 4-8 hour turnaround for the DBA to make that change in the Development database, so clearly this will increase the estimate too.  The same is true for testing:  Sometimes a simple enough fix causes all sorts of retesting.

So, instead of measuring estimates in hours, we need to measure estimates that consider:  size,  risk, complexity, prior knowledge and other factors such as elapsed time and testing impact.  For the lack of anything better to call it, let’s pick an arbitrary measure for this estimate and call it a Point.

Now, we can look at one of the stories we need to do, and say, arbitrarily, “This User Story is worth 1 point.”  Now, let’s estimate the other stories based on that first User Story.  Perhaps the second User Story is not as well defined and will require some developer research, it is also more complicated, so let’s say that User Story is worth, 5 points?

If we do this with just any numbers, then we run into a special kind of madness where we are splitting hairs over the difference between a 12 point apple and a 13 point orange.  Not only are the problems dissimilar, but since the 1 point item was arbitrarily chosen, the difference between a 12 and a 13 is quite nebulous.  For this reason, most agile teams use only specific numbers when estimating points.  These are typically:  0, 1, 2, 3, 5, 8, 13, and 20.  (This sequence is based on the Fibonacci sequence.)  Note that these are also integers, so there is nothing like 0.5 Points; the User Story is either 0 Points or 1 Point in size.

A lot of people don’t like the completely arbitrary selection of the value of a Point.  If instead, we say that a 1 Point User Story is roughly what one developer can accomplish in a standard day with no risk and easy complexity, then we have a basis for comparing the other numbers, a 2 is either twice as big, twice as hard, or twice as risky.  A 3 is probably some combination of these that make it likely to be 3 times bigger than a 1, and so on.

Further, a 0 is any User Story that’s a “gimme”.  If the developer says, “Oh, that’s no problem, I can have that fixed in 5 minutes,” that’s a 0 Point User Story.  Note, that ten 0 Point stories do not add up to 0 Points as ten little stories can easily take a day to accomplish.

Finally, there is 20.  Essentially, any User Story that is big enough to make you want to give it a 20, is too big to be estimated well, so a 20 is more of a red flag than a  legitimate points value, but this value allows you to estimate all of your stories, regardless of their size.

(Some teams include the integers 50 and 100 in their estimating.  This makes 20 just a big story, 50 is a story big enough to fill a sprint and 100 is the red flag that the story is too big to estimate.  I prefer to max out at 20 points.

In Summary:

Points are an estimate of size, risk, complexity and other factors such as prior knowledge, elapsed time, and testing considerations.

Points are typically an integer in the sequence:  0, 1, 2, 3, 5, 8, 13, and 20.

Points allow us to estimate the relative size of each story.