We tell fantastic stories
When we need to describe how a project should be built, we use a technique called Story Driven Development. Using stories involves describing the desired behaviour or goals of a project.
Stories describe what needs to happen in short, descriptive chunks- think of it as Spec Haiku.
The (not so) magical spec doc
We don’t use spec docs. I’m sure they are useful in some industries, but we’ve found that they aren’t that suited to making stuff on the web. A spec document typically tries to list out all the different things and features of a project. If you’re looking for detail on any area of the project, you can check the spec and find it there.
This approach probably works well if I was making an ATM machine – all the inputs and outputs are clearly defined. I type in my pin and ask for $20. I should get twenty dollars out. But as a web project increases in complexity (ie: when the development team need some kind of reference) they seem to become cumbersome and unwieldy. They tend to help you focus on the detail rather than the big picture.
To clarify: just because we don’t believe in the spec doc fairy doesn’t mean we just sit down and belt out stuff without planning it out carefully. We just use a different, more suitable technique.
When spec docs go feral
Web projects seem to have a habit of evolving – what seemed like a good idea at the start could be done better this way. Or we really need that feature in sooner. Despite everyone nodding their heads about the spec being “a living document”, the update task grows bigger and bigger. As it stops being updated the team stop checking it. And so on. They also tend to include a lot of redundant information, due to copy & paste-itis.
If the final deliverable goes awry, then the blame game often begins about what was in or out of scope. Urgh.
Example – getting that tree but missing the forest
We were working on a site that had a membership feature. People could sign up from any country, and they then got a country specific version. We were sent a spec doc covering the membership process, but most of it was taken up with a list over about 12 pages of the name of every country and it’s country code. This spec doc completely nailed the not so important “make sure we cover every possible country” problem, but completely missed other features that might be important to users. Such what should happen when someone that joined before the new site comes back and tries to use the new form to rejoin (should they get an error? Ideally there would be no error and we’d update their details…)
A more story/goal driven way of describing this might be:
“As a new user, I am able to join from any country”, and perhaps
“As an existing user, I can fill out the join form without feeling like I’ve done anything wrong”
You can see that 12 pages has become a few words (OK- I’m cheating a bit and using very simple story examples). This approach does rely on the developer to be smart enough to find a list of countries (I guess there are entire ISO standard bodies just for this). Lets assume that they’ve managed to get dressed themselves this morning, and they are relatively smart cookies so can figure that out.
Stories become part of the code
The interesting bit happens when the story becomes part of the code. Stories are useful for describing what the project needs to be (and you don’t need to be technical to read or write them). They become incredibly useful when they get integrated into the project. Once a story is reviewed and we’re happy, it gets assigned to a developer. They then flesh it out a bit more and write their code around it.
As they build that feature, they also start to write tests. This is one of the great features of the more modern development frameworks like Ruby on Rails is the integration of tests. So the “I can join from all countries” was a key feature, then there would be a test that would actually test whether this was possible.
Every time the tests get run (typically when a new feature is added or version deployed), this story gets tested. The original requirement has become embedded into the code- we don’t need to refer back to a document. The test either passes or fails. If someone decides that the form is too long and removes the country listing, the test will start to fail and the developer will get an alert.
For more details on using stories and how to write a corker, please see Dan North’s article