Recently, Zach Young, a colleague of mine, and I started working on a project with the goal to learn several new things. I had the idea for the application, a simple web application that would displayed the post from registered RSS feeds sorted by publish date.
Which sounds pretty simple, but it became more clear the more we talked about it that we needed requirements. It is the same problem that is apparent in any software projects. I am, for this instance, playing the role of the customer, and I have a vision of a product I want someone to build for me.
The Problem
The problem is getting this vision out of my head, where it is perfect, of course, and into a form that can be clearly communicated to the development team so that I can feel confident that what they deliver will be what I ask for.
I spent a few days diving into Use Cases and found that I didn't feel like I was getting anywhere. I was typing a lot of information but still didn't feel like the developer would get what I am saying. A quick phone call to another colleague, Raymond Lewallen and I was off checking out User Stories. And guess what they are small, light-weight, easy to write and easy to read.
So what is a User Story?
Well, according to wikipedia, A user story is a software system requirement formulated as one or two sentences in the everyday language of the user. This was exactly what I wanted. Since this is a side project and mainly to be used to learn, I don't want to spend all of my time writing tomes of requirements documentation before I get to writing some code.
Dan North: What's in a story
I decided to create User Stories following what Dan North has introduced in his What's in a Story post.
The simple format of the BDD style user story is quick to write and ubiquitous is easy to achieve. Let's take a look at the format.
Title (one line describing the story)
Narrative:
As a [role]
I want [feature]
So that [benefit]
Acceptance Criteria: (presented as Scenarios)
Scenario 1: Title
Given [context]
And [some more context]...
When [event]
Then [outcome]
And [another outcome]...
Using this has allowed me to get the requirements documented quickly, in a form that both Zach and I can easily understand and we rarely have to go back over what is in the user story for a feature and could move on to learning how to write test to satisfy the user story.
If you are interested in checking out our project and looking at the User Stories we are developing you can find it at http://code.google.com/p/hermesreader. This project is intended to be an educational and you are interested in helping out drop me a line.
I will continue to post regarding the progress and concepts are are applying to the project as we tackle them. Hopefully this information will save you some time and help you get the code out the door.