User Stories
Steven J Zeil:
Abstract
User stories are used in incremental SDPMs as a way of organizing work during software construction.
A user story is a simple description of desired functionality, often written as a single sentence on an ordinary index card.
Over time, user stories are modified by
- adding an estimated effort to implement that story.
- adding priority info indicating how important this story is to the end users.
- splitting stories that are too big to be implemented during a single pass of an incremental process
- merging related stories that have become too detailed to implement separately.
In an incremental construction process, small sets of stories are chosen for an upcoming increment as the target for the next round of construction.
1 User stories
Key idea in all agile variations.
A user story is
- a mechanism for incremental requirements elicitation and analysis.
- a way of organizing and tracking work during iterative development
“I imagined a user grabbing another user in the hallway and saying, ‘I gotta tell you about this wonderful new thing the application does…’ Stories are the stories customers wish they could tell about the system but can’t (yet).”
– Kent Beck
1.1 Writing User Stories
- One or two-line description of work to be done
- Usually written on index cards
- Often posted on a bulletin board in team workspaces
- Each story describes something of value to a customer
- e.g., “Complete the integration tests” is not a story.
- Stories have clear completion criteria.
-
They must be validatable.
-
1.1.1 Examples of User Stories
As a calendar owner, I want to view my schedule for the coming week.
As a visitor, I want to see when a calendar owner has free time in their schedule.
As a calendar owner, I want to receive email notication when someone accepts a proposed appointment.
As a systems administrator, I want to back up all calendars so that the data is safeguarded.
These illustrate some common patterns:
- “As a
{role}
, I want{goal/desire}
” - “As a
{role}
, I want{goal/desire}
so that{benefit}
”
1.1.2 Stories are not Requirements
…despite the focus on functionality and non-functional characteristics.
Stories can be used as a tool for eliciting requirements:
- Stories are “a promissory note for a future conversation” (Cockburn)
- A use-case is a transcript of that conversation (Standley)
We will focus, instead, on the use of stories as a way of prioritizing work * A team begins each increment by selecting a set of stories that add up to a desired behavior. * At the end of the increment, that new behavior can be demonstrated to customers.
1.2 Characteristics of good stories
1.2.1 Customer centric
Stories should express a customer’s point of view, using the customer’s language.
- Who is the customer? (What customer role is affected by this story?)
- What is the value of this story to the customer?
- Which customers is this story important to, and how does it affect them?
One way to achieve this is to ask the customers to write the stories.
- Stories should be rated by customer priority.
- If the customers do not write the stories, they can still rank them.
Who is the Customer?
Never write a story where the user role name is given as “As a user, …”
-
“User” is the word we write to indicate that we are too lazy or too clueless about who the real customers are to come up with a properly descriptive name.
- It’s the equivalent of naming a variable in your code
data
orvariable
.
- It’s the equivalent of naming a variable in your code
-
Similarly, the development team are not the customers for the system. Don’t write “As a programmer, …” unless the project is a code library for use by programmers on other projects. Even then, try to use role names that distinguish those future programmers form the current development team.
- E.g., when developing a library, you might talk about “application programmers” as a user role.
1.2.2 Estimatable
At some point in the process, we must add estimates to our stories indicating how much time we think it will take to complete them. Such estimates aid us in future scheduling. We want to select, for each upcoming increment, enough stories to add a substantial amount of functionality, but not so many that we will be unable to complete them in the time allotted for that increment.
The estimates are commonly not written in hours, person-days or other real time units, at least not unless your team is actually experienced enough to do a good job at coming up with such numbers. Instead, a groups of “typical effort” stories is selected as defining unit 1.0 difficulty, and the others are expresssed in numbers relative to that, e.g., “I think this will take half again as long as the typical stories, so I will estimate it at 1.5.”
-
The team must estimate the effort required to implementation a story.
- Often done on a relative scale.
“This story will take half again as much time as our average story.”
- Often done on a relative scale.
-
Big, complicated stories (“epics”) are harder to estimate
- Split them into smaller stories
1.2.3 Validatable
Good stories have completion criteria that can be validated.
-
It’s important to know when we are done implementing a story.
-
Agile generally recognizes stories as only 0% or 100% completed – no fractions.
-
Definition of Done: team’s agreed-upon criteria for declaring work done (e.g., tests passed, integrated, documented, …)
A common saying among agile teams:
“I know that you are done, but are you DONE-done?”
-
Non-functional stories
Stories can describe new functionality or improvements to existing functionality:
- Performance requirements,
- Scalability
- Portability
This is generally done very late in development, or when the project centers on modification of an existing system.
A challenge can be defining precise completion criteria. * Many of these goals cannot be said to have been resolved until the end of the project, making them unsuitable as units of work to be assigned during a single increment.
1.2.4 Some Examples of “Bad” Stories
Automate integration build
- no customer value
Improve performance
- no completion criteria
Implement interfaces between subsystems
- too big – cannot be accomplished by 1 or 2 people in a short period of time
- has “obvious” decompositions (separate interfaces between each pair of subsystems) that would make it more suitable
1.3 Example (Spreadsheet)
- Look at these stories
1.4 Special Stories
The traditional user story is customer-centric.
But sometimes there are units of work required that don’t fit the traditional definition.
1.4.1 Documentation stories
- Agile places less emphasis on documentation
- Most (e.g., API documentation) is just factored in as part of the effort of implementing a normal story
- Occasionally, special documentation needs arise
- user manuals, certification requirements
1.4.2 Bug Stories
- Fixes for bugs that evaded your unit tests
- Can be hard to estimate effort
- allocate fixed time, then schedule a “sequel” story
1.4.3 Spike Stories
- Can’t estimate some stories because of lack of information
- Spike stories say “Research how to estimate story X”.
- Name comes from practice of spike solutions, simple throw-away prototypes or experiments
2 Organizing Constructions via Stories
Remember that each increment is supposed to yield a runnable program that implements some addition functionality not present in earlier increments.
- Something that we can actually show to a manager/customer/user
Stories also add functionality, but an individual story might not yield something visible while running the program.
2.1 Planning an Increment
In planning our next increment or release, we select a set of stories to be implemented during our next development interval.
-
Together, they should add up to a visible addition of functionality to the working system.
-
Use the estimates attached to each story to scale the amount of work planned for this development interval to a reasonable size.
-
Early in a project, we might need to guess just how much time it will take to 1 estimated unit of effort.
-
This should become clearer as we move forward through the project.
-
2.1.1 Posting Stories
There are a variety of ways to visually organize stories to enhance planning and to give visual evidence of the progress being made.
- Stories grouped on a story board to help “enrich” the stories
- Story boards can be organized in many different ways
Some development teams will favor an on-line version of a task board. Here, for example, is a board for a recent project of mine.
- This is actually a snapshot of a point during the development of the project. A number of stories have been marked as completed, one is in progress, and a number are still waiting to be picked up from the backlog.
- Clicking on any of the rectangular “cards” will open it up to let you read the full text of the story and any related notes.
Try opening the story “View language summaries”.
- In the Description area, you see the full text of the story.
- Looking above that, you can see that I have claimed (members) this as something that I will work on, that the card is labeled as a “story”, and that it has been allocated one point of effort.
- Below the description, in the “To be done” area, you can see that I have split the story into three tasks, one of which is marked as completed.
- Click the X in the upper right hand corner to close the story card.
-
When a story is completed, I would simply drag that card to the “Completed” column.
Try opening the story in the “Completed - Sprint 4” column.
- You can see that the internal structure is similar to the other card’s, but, this time, all tasks are marked as completed.
2.1.2 Backlogs
A term used in conjunction with story-based planning is “backlog”.
-
In normal English usage, “backlog” sounds negative: You have a backlog because you are “backed up” – your progress has been too slow.
-
In incremental development, there is no such negative connotation.
-
The project backlog is a list of unimplemented:
- Stories, or
- Requirements for which stories have not been written.
-
3 Stories Divide Into Tasks
When we pick up a story for development there may be many steps required to actually complete it.
- Typically we indicate this by listing (often on the same card as the story) the required tasks.
- We then track the completion status of individual tasks.
It’s possible that a developer will do some tasks on one story, then move to tasks of a second story, then return to the first, etc.
3.1 Tasking Example 1
In the spreadsheet stories, I suggested that the stories for the first increment might be
- As a calculation author I would like to load a spreadsheet via the CLI.
- As a calculation author I would like to generate a value report via the CLI.
- As an API user I would like to create a new spreadsheet.
- As an API user I would like to load a spreadsheet from a file containing only simple assignments.
- As an API user I would like to add a numeric literal to a cell in a spreadsheet.
- As an API user I would like to obtain the value of a cell whose formula contains only literals.
Of these, I would likely pick
- As an API user I would like to create a new spreadsheet.
to start.
Then, I would break it into tasks, some of which would be necessitated by this being the first story developed in a project:
-
Set up project repository
-
Set up directories and initial build file.
-
Design initial spreadsheet API.
-
Write unit test for spreadsheet creation via that API.
-
Implement the spreadsheet creation function.
-
Commit implementation to the repository.
Some comments about these tasks:
-
The italicized items are all concepts that we will tackle in a subsequent lesson.
-
The sequence defined by items 3-4-5 is characteristic of Test-Driven Development:
- We always write a test that will initially fail (if it can be run at all) before doing the implementation.
- That way we
- know when we have succeeded with our implementation.
- already have a test driver ready the moment we have written part of the actual code.
- Although, eventually, we will have an entire test for the spreadsheet API, we don’t try to do that all at once. The tests are written incrementally, just like the application itself.
3.2 Task Boards
-
Task boards show the completed and in-progress stories for the current increment:
- On this board, the stories are in the cards on the left.
- The post-it notes represent tasks, and are moved to the right as progress is made.
- The post-its often have the name(s) of the developers that have taken on each task.
-
The “To do” column is sometimes labeled the “sprint backlog”
- This is the collection of not-completed tasks scheduled for the current increment.
- The name comes from the Scrum agile process model, where a period of development for one increment is called a “sprint”.
Again, on-line versions of task boards can be popular. This is an example using OpenProject, for the same project as for the earlier story board example.
- Clicking on the ▼ alongside Sprint 2 and selecting “Task Board” opens this board.
- Stories are in the leftmost columns.
- Arranged in the “swimlane” to the right of each story are the tasks for that story.
- Clicking on the ID number in any of the rectangular “cards” will open it up to let you read the full text of the story/task.
-
When a task is completed, I would simply drag that card to the “Closed” column.
4 The Definition of Done
"I know you say that you are done. But are you done done? – apocryphal question from one team member to another.
The definition of done is a set of criteria that must be met before a development team agrees that a story has been completed and that the people assigned to it are ready to move on to tackle something else.
- Typically, this definition is established by the team at the start of the project.
Typical Criteria in a Definition of Done
- Code passes all unit tests.
- System level (functional) tests have been created/passed.
- Code is checked in and shared with the rest of the team.
- Code has been integrated and is used by other code in the project.
- Code meets documentation standards.
- Code has been reviewed by other team members and found free of major problems.
- Code has been reviews by analysis tools and found free of major problems.
4.1 Tasks can Follow the Definition of Done
One way to divide a story into tasks is to turn each criterion chosen for the teams’ DoD into a task.
4.2 Tasking Example 2, OpenProject (Spreadsheet)
5 Thinking Incrementally
To me, one of the challenges in designing good stories and in scheduling them is to envision possible increments.
-
When a large portion of the implementation is done, this is relatively easy.
- Just list the missing features. Adding a feature (or two, or three) is a “natural” increment.
-
But what about when you have nothing at all working yet?
- It can feel like you need to get a massive amount implemented before anything works at all!
5.1 Vertical Thinking
- We design code in “horizontal” layers of abstraction.
- But an increment is a “vertical slice” of functioning code.
5.1.1 Iterative Means We Can Come Back
-
Incremental development is also iterative – we can revisit components in later iterations.
-
Sometimes that’s easy.
- It’s usually pretty easy to implement part of a menu or toolbar.
- Part of a window is usually easy too
-
Sometimes it’s not
-
Think of a typical ADT - how can you implement part of it?
-
5.1.2 Faking It
If we need to implement part of a complicated ADT during an increment…
-
Choose a quick (to implement) data structure now, with the intention of replacing it later when we need more of the ADT API to work.
-
Or, take a lesson from integration testing
- Create stubs for unimplemented lower-layer components.
- Carried to an extreme, you can be pnambic