Detailed User Story
Story221UserBrowseListOfVendor_Product (.pdf, 52 kb)
Audience
Development team including QA; product owner; other stakeholders occasionally
Team
Myself in conjunction with product owner and lead developer
Challenge
Convey concept and details about a feature to be built
techniques & tools
User story template; brainpower
outcome
Perhaps nearly crossing the line from agile-user-story-with-notes to baby-waterfall-requirements-doc, these user stories documented conversation and facilitated shared understanding.
The Problem
At Pathfinder Software, the job of writing user stories fell primarily on the user experience person assigned to the team or project. We used a template that had been handed down since time immemorial, or at least four or five years. User stories were kept in a wiki-like environment so that anyone involved could edit them, and previous versions could be compared if necessary.
Blow by Blow
The user story document is broken down into 10 sections, each meeting specific needs.
User Story
This section is a simple statement of the feature’s outcome from the perspective of the user. It is written in the agile-classic format of “As a [user role] I want to [action] so that [supporting detail of user’s need].”
1. Story Details
This section allows the writer(s) of the document to add detail of almost any sort. The classic as-a-want-to-so-that statement of a user story is great for shorthand description, but invariable there is detail that needs to be added.
2. Assumptions
Just like any feature description, we need to document our assumptions.
3. Out-of-Scope
It was our practice at Pathfinder to be sure to explicitly declare what work was not to be done as part of this story. This was also a place to note when some of that out of scope work might be done in future stories, putting a stakeholder who might read this at ease that their pet feature had not been forgotten.
4. Questions and Issues
This was a living document, and during discussions, questions would arise. Rather than try to chase down the answer to every concern all at once, or wait until every possible thing was known, this is a place to leave open questions. Too many open questions are a strong signal that the story is not complete enough to take to development in a sprint.
5. Dependencies and Related Stories
References to other stories upon which this story relied. Since story creation would take place in an exciting jumble of ideas, sometimes a story depends on a higher- (thus later-) numbered story. That’s nothing to worry about, the numbering is just an identifier.
6. Flowcharts or Other Diagrams
Not always necessary (and there were none for this sample), but if any kind of chart or diagram would help explain the story, this was the place for it.
7. Wireframes or Screenshots
The fidelity here was consciously low. At Pathfinder, and as is possible in many agile environments, the visual designer was part of the development team, and a high-fidelity mockup was not necessary for a story to move to development. Even the wireframes could be pretty crude. At this company, the employees were all co-located in an office in Chicago, the workspace was decidedly open-office (move your chair, laptop and file drawer if you were using one to be together with your designer and developers) so everyone could look over everyone’s shoulder—in the politest way possible, of course—to give and get feedback. And the visual designs or guidelines for a project were set early on and understood by all.
This also required the establishment of trust between the client stakeholder and the team. Trust is under-represented in discussions about process, but basically the more trust there is, the better an agile process will work. Anyway, that’s why the wireframe in this sample looks like a hot mess to you, and yet it was just fine for the team working on the project.
8. Acceptance Criteria
Working in a fairly fast-paced environment, and therefore not taking much if any time on clickable prototypes, it cannot always be assumed that everybody understands what all elements on a screen do. I can’t say that I was the only one who used this old-style “use case” format for the acceptance criteria, but I know that I pushed it as a good example. Even though it’s a lot of words, this kind of criteria improved understanding of the interactions on the screen and also framed the testing protocol.
9. Developer Notes
As you might guess, I did not have to write much in this section.
The Upshot
I wrote a lot of these user stories while I was at Pathfinder, so I got pretty good at them. More importantly, these written documents opened the door to good conversation and served as a place to document the shared understanding created by those conversations.