Ruby Red Bricks

Today in our end-of-week get together the team discussed treating requirements with a little less care than we currently do. Probably like a lot of places out there, we diligently enter our requirements into a tracking system (currently Mingle), schedule them for work, implement and test and then finally – if everything goes well – close them as part of a release..

..and then never look at them again.

Over time a lot of cruft gets built up – old requirements that may / may not be still relevant.. huge amounts of data that is pretty difficult to search through.. a big inventory of past work that could be considered – in the lean sense of the word – as waste, i.e. it provides little or no ongoing value.

The outcome of the meeting today was to allow requirements to go through their normal life-cycle, reach a final stage of user acceptance – and then be thrown away. We’re even considering going back to using just plain 3”x5” cards for recording requirements and then tearing them up once the work has been successfully completed from the clients’ perspective.

The argument for doing this is that the code and the application itself is the best documentation of an application’s functionality – any documentation should be derived from it and not from some abstract or alternative representation. This requires some discipline: when I say “code” I include test code. Specifically I mean using Behaviour Driven Development (BDD) and capturing the specification of an application in a form that is comprehendible by both developers and end-users alike.

Because we’re a Rails shop and use both RSpec and Cucumber we can translate requirements into executable specifications, e.g.:

Given that I am I new user
When I register a new account and enter my details
Then I will be emailed a welcome message advising how to activate my account

describe User
  it "MUST have a password longer than 6 characters" 
  it "MUST have a unique login id"

Once these are entered into the codebase, test code is written (and passes!) these become the canonical specifications for the application, the ultimate statement of what the application actual does and what constraints exist. Often during the course of development we’ll come across new requirements – or clarify existing ones. The neat thing about most BDD tools is they generally allow you to print out a text-only version – a document that can be cheaply and frequently presented to the customer detailing the actual and proposed features of the system to confirm that development is on the right course, with the right understanding of what the customer wants.

Naturally there are other ways of recording requirements that can’t be covered by BDD. One important artifact we use all the time is the Wireframe – but again this is a temporary artifact. Once the app has been implemented the best definition of its look and feel is the application itself.

Some customers will require more permanent requirement artifacts. That’s fine, we can do that to satisfy contracts – but it will probably be the exception to the rule. We may need to create additional artifacts in different situations. Again fine, but let’s start with a simple model first and see what we need to do to complicate things.

OK, I’m tired.. and it’s been a long week. But I think that makes sense. Yeah?