User Stories
You will capture the functional requirements of your system in user stories, a popular agile method for documenting and writing down system functionality. A user story is a concise statement of something that a user should be able to do with your system; in some sense you are capturing a feature or capability of your system, but from the user’s perspective. This is useful because it forces you to stay focused on why this capability is justified in your system.
Each user story you create must have a number and title and then must have its main story statement in the form of:
As a [role] I/we want to [capability] so that [goal].
The role is the type of user for this capability, the capability is what they want to do with your system, and the goal is why they want to do this with your system.
A user story also must have an elaboration and constraint description, and it must have an effort estimation using dimensionless Fibonacci numbers. For a starting scale, consider your entire project to have an estimate of perhaps 144 or 233 (both Fibonacci numbers). The story ID number must be a dotted hierarchical number indicating which larger stories are its parents (if any). It also must have an acceptance test description, which should be a short description of how you will validate that this story was successfully implemented.
NOTE: user stories are user stories, not developer stories! You (as a developer) are not a user!
An example (for some business team management app):
============== begin example ==============
3.6: Export to CSV
Story: As a manager, I want to export my team’s timesheet data to a CSV file so that I can use it in a spreadsheet or write a script to do my own processing.
Elaboration: Users should have the ability to use their data for purposes outside our system, and so we need to support a data export capability; since the CSV (comma-separated-values) file format is fairly common, we will use it as our export format.
Constraints: none
Effort Estimation: 8
Acceptance Test: Perform export operation in user interface on demo data and import the resulting CSV file into OpenOffice Calc and Microsoft Excel. Show that both apps import the CSV properly. Perform export on a set of demo data, on data containing 1 element, and on an empty data set.
============== end example ==============
The number of the above story, 3.6, is indicating it is user story 6 within top-level user story 3. What is user story 3? Perhaps it is:
3: Integrate with other tools
Story: As a manager, I want to integrate this system with other tools I use so that my overall workflow is seamless.
[rest of story parts would be here]
As you can see, higher level user stories (epics!) can be very abstract and not much help in figuring out your system, but they can then be broken down into pieces that finally tell you what you need to do!
Guidelines and Caveats
Do not put functionality in the goal part: It can be tempting to write a user story in a way that puts some functionality in the goal statement; this causes you to miss writing down that real user goal that should go along with the user story functionality.
Here’s an example of this: “As a grocery store customer I want a camera integrated in the checkout system so that the system will automatically recognize my produce item without me looking it up.” (note: produce items typically do not have barcodes to scan)
The user story at first sounds reasonable, but it places most of the functionality statement in the “so that” part, but it should be in the “I want” part. This story should be re-written as:
“As a grocery store customer I want the checkout system to automatically recognize my produce item without me looking it up so that I can check out faster and avoid the hassle of scrolling a menu of items.”
The goal after the “so that” phrase should be a life goal of the user, not a more detailed statement of the functionality of the system feature.
Strive for SMART and INVEST-ed user stories: These two acronyms capture a set of attributes that good, usable user stories should have. You can find lots of reading out there, but a couple are: VisualParadigm:SMART and AgileAlliance:INVEST.
Resources
Mountain Goat has a blog post about not everything needing to be captured in a user story.