Requirements are dead. Long live requirements.

We were really suffering from some of the classic problems mentioned in Mike’s book including:

There was so much in that book that had me nodding my head and thinking “Yep!” with every page. Of course criticizing traditional style requirements documents isn’t hard. I don’t know that I’ve ever met that many people who don’t have a story or complaint about how bad they can be. They’re an easy target and I have something more useful (I hope) to say. I’m not going to rehash what user stories are or how they may benefit you. If you’re not already familiar with them I heartily recommend that book mentioned above. For a more immediate introduction hit up Google and you’ll find plenty of material.

What I want to talk about is how to balance working with stories with environments that are looking for something a bit more traditional when it comes to requirements specifications.

The industry I work in provides services to the pharmaceutical and biotech industry. The work we do is subject to FDA guidelines and the audits (from internal quality groups, customers and potentially the FDA themselves) that go along with them. This has bred a certain set of expectations amongst auditors, not least that there will be a classically styled requirements specification from which they can trace design, implementation and verification and validation of features. Overcoming this expectation may eventually be possible. Perhaps even as soon as one, maybe two decades ;-) but for now trying to do so is tantamount to pushing water up a hill with a rake.

Given this situation, we (and I strongly suspect we are not alone here) still need to produce something that we can call a requirements specification, print out and sign and show some kind of traceability to our tests. There have been a handful of ideas over time on how we might do this. Different Scrum teams in my organization have tried different things, but I’m not sure that any of us yet have got this completely licked.

The first approach was really just business as usual. That is to say that although we had a backlog of stories, they were really just placeholders for work. We still captured the detailed aspects of what we were building in a traditional Requirements Specification. Our “Definition of Done” actually included “update RS” as an item for every story. This idea more or less worked, although it felt a little unwieldy. All the classic problems of big RS documents remained with us, we just bit things off a story at a time which definitely aided us in some ways (not least by eliminating the need to write the entire thing and sign it off before beginning to work).

We also flirted briefly with use cases, which if you do even a moments research, will allow you to find various “templates” and so forth for authoring them. The problems we had here were twofold: Firstly, a good use case is actually larger than a story. So with us trying to take story-sized pieces of work and describe them in use case format things got kind of artificial and we created more work for ourselves. If we’d carried on down that path we would have had innumerable documents, since each use case was its own Word file. Secondly, use cases seem best suited for very GUI centric functionality with obvious human “actors” interacting with the system. For web services and other non-GUI work they seemed quite hard to do well, seeming to come out quite convoluted. Sure, you can have the other system as an actor but nonetheless things came out weird. Maybe we sucked at writing use cases, but in truth I suspect they just really weren’t the right tool for capturing story requirements.

Around this time I had just finished reading Gojko Adzic’s Bridging the Communication Gap which introduced me to concepts like specification by example and acceptance testing. These ideas resonated with me and seemed like useful, sensible things we could try out. As an alternative to the use cases we were writing I proposed a story + acceptance criteria with examples template (heavily influenced by Gojko’s book) that I thought we might try. In actuality this never caught on. Perhaps it’s just as well because with hindsight, the idea of requirements scattered across hundreds of documents violated one of my own big pet peeves about our prior approach: no good narrative providing an overview of different product areas.

One reason that idea may not have got traction was perhaps due to the fact that we had started to make use of the Rally tool for agile project management. I’m actually not a big fan of Rally’s tool (more on that here if interested) but nonetheless, in our "new toy fervor" there did seem to be an exciting chance to do away with Word document based requirements altogether. In our environment this was a radical proposal which I firmly supported…if only it weren’t for those auditor types who want to see one. As a response to this the idea of exporting story details from Rally emerged. This made sense at the time too. One of the pieces of advice I’d seen from several people was, “If you need to keep a written spec, just keep the story cards” (or in our case, the story records in Rally). Rally’s product has a set of web services and various ways to interact with them, including a simple Ruby script for importing and exporting data. It does work, but it’s pretty simplistic at this time and requires quite a lot of effort to convert the CSV output into anything resembling a normal looking requirements document. It would certainly be possible to hack away on that script or create your own variation on the theme that was a bit more geared to the specific task of creating this kind of output. But, I’m no longer convinced that’s what we want to do.

Most recently, in anticipation of a brand new product starting I’ve been reading about and dabbling in behavior driven development (BDD) and acceptance test driven development (ATDD). In particular I’ve been looking at Cucumber and Cuke4Nuke (which enables one to write “test fixtures” in C#). See here for my first post after encountering Cucumber. Something this exposed me to was the “Given/When/Then” (G/W/T) form of expressing requirements. Even without automating your tests and doing full ATDD this simple approach to describing requirements seems to be pretty powerful. In many ways the G/W/T stuff seems to stand on the shoulders of use cases, but feels more lightweight, simpler and provides an easier time of things when it comes to splitting features into smaller parts.

One thing that I thought had lodged firmly in my mind after all this was the idea of tests as your specification, or “executable specifications.” The concept is simple: if your tests are readable and express what the software should do, then the running of them indicates what it actually does and you’re never playing “catch-up” with an old school requirements specification.

And yet…clearly this idea hadn’t stuck. My team was discussing last week whether we had to keep our RS for our legacy product and whether we could maybe forgo such an artifact for the new product we will be starting soon. We got onto talking about how we couldn’t just document things in Rally because the export wasn’t good enough for what we needed. I resolved to try and do something about this by investigating the export script. And I was doing so when I realized that this was completely the wrong problem to solve. I hadn’t seen it as clearly before, but I realized then: stories are transactional. They only make sense if you review them chronologically because story #42 can completely modify the feature you put in through story #7. Keeping your stories and transforming them into some kind of document as a surrogate requirements specification isn’t the right approach. Instead, we should be transforming our tests into a specification because they represent exactly what the product is meant to do in a much more succinct way than a huge transactional list of stories.

Of course to do this one needs tests that are human readable, and not just by humans that can interpret code. This brings us back to the Given/When/Then format, because it sits natural language descriptions on top of automated tests. And, lo and behold, it’s entirely possible to very easily transform your Cucumber feature descriptions into various outputs, including a PDF.

When we first embarked on transitioning to agile software development I wrote a series of four blog posts about our early experiences. I concluded with looking forward to where we would need to focus next. I said at the time I thought requirements would be a big deal for us. It’s taken longer than I anticipated, but I think now we can start to see a path forward.

We don’t want to have a big old requirements specification that we maintain. We do need to have something that helps us meet our regulatory obligations. ATDD and the G/W/T approaches can help us with this. We can generate what we need as a natural part of a work that’s far more integrated into software development than a traditional document ever could be. Requirements are dead. Long live requirements.