Agile Zone is brought to you in partnership with:

Jon Archer is a software professional with over 15 years experience who is lucky enough to work out of his mountain retreat high above Denver in the Colorado Rockies. He has worked as a software engineer with various technologies during the course of his career as well as a couple of diversions managing teams. These days he is the scrum master for a challengingly distributed team with members in Massachusetts, Colorado and Hyderabad India. He is a passionate believer in agile principles and is a key advocate thereof for his current employer Perceptive Informatics. He blogs at and tweets as @9200feet Jon is a DZone MVB and is not an employee of DZone and has posted 19 posts at DZone. View Full User Profile

Requirements are dead. Long live requirements.

  • submit to reddit
One of the first “Agile” books I read that really inspired me to change how we went about creating software was Mike Cohn’s User Stories Applied. I think it’s because, perhaps more than anything else in my career in software development, I had seen problems that boiled down to “requirements problems”.

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

  • People not really understanding what needed to be built or why, but just focusing on making sure the software did what the requirements said because the requirements couldn’t possibly be wrong...
  • People obsessing over where commas went (when ironically the basic words in play were not always comprehensive enough for us to worry about punctuation that much)
  • People testing what they thought the requirements meant, rather than what the customer needed.
  • Requirements fatigue – huge weighty tomes of requirements typically starting “the system shall…” and yet rarely  any decent narrative providing an overview. This kind of stuff would put an insomniac to sleep.
  • Ambiguous wording, cryptic wording and just plain iffy writing: many times things were being phrased  to suit a business analyst, software engineer or tester’s view of the world. Often this rendered the document almost impenetrable to our customers who we expected to sign off on it(!)
  • Conversations and emails that involved convoluted phrases like “…but don’t you realize that requirement clearly means that in this context…”

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.
Published at DZone with permission of Jon Archer, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)



Eric Bresie replied on Thu, 2010/10/21 - 1:47pm

I think folks often times forget something regarding requirements. Requirements are written so that all stakeholders, not just developers who understand a specific programming language of the moment, but all stakeholders (business units, managers, users, developers, testers, QA, manufactures, regulators, etc) are able to agree upon what the system does.

I think that is a major problem in SW projects is that developers develop in code which avoids lots of extra paperwork. However this completely prevents good communications and good understanding by other parties.

Agile practices do promotes involvement by the customer so in many ways that does address some of the needs, but that still assumes that customer and developer understand what is being developed. Failure for all to understands risks building what is not wanted or risks failing to identify and implement all needs of the product.

I recommend Mastering the Requirement Process which gives a good discussion on requirements and different flavors of agile/requirement scenarios.

Mike Dobbles replied on Fri, 2010/10/29 - 7:54pm

I don't think specification in the form of "the system shall" benefit all stake holders as the comment above by Eric suggests. Rarely have I seen marketing or executives take the time to truely wade through these documents and then successfully come away with a good understanding of the product specified. In fact the only ones in my experience who truely deeply attempt to understand specifications are engineers and as I argue in my posting "Can and should agile be used for medical device development? Absolutely!" I think it's often to the detriment of the project because these documents are typically deeply flawed due to the fact they are often made at the beginning of a project before any one really knows what they're talking about. That said, I do think there is one group that these documents work well for and that's an independent V&V group. I think it's useful for them to have a contract for how the software should operate that they can then verify. In effect this turns the very notion of the role of a specification in a waterfall project on it's head. Instead of writing the spec at the beginning of the project, you don't need it until near the end. In practice, this is what I see most projects do any way. They write deeply flawed specs up front, follow them during development only in the loosest sense, then write the real specs at the end of the project. But what about collaborating with other stake holders and making sure the engineers build the right thing? I think getting stake holders and engineers on the same page is very important and very difficult. I don't think one document can do it. I am absolutely positive that a document formatted "the system shall.." can't do it. To get every one on the same page I think a mix of all the elements Jon mentioned in his article can help. Write a narrative, create user stories where they make sense, document examples, develop specifying test cases, and do anything else you can think of, then start iterating and demoing product. Only with constant communication and a tight feedback loop during development will you get everyone pointed in the same direction. And once every one is pointed in the same direction, writing a spec will be easy (and the V&V group and FDA auditors will be happy with that spec you write).

Ellen Gottesdiener replied on Sat, 2010/11/20 - 5:06pm

Thanks for your post!

Making Ready

One thing we've found in working on agile projects is that slicing requirements based on value and sound analysis of the requirements can really accelerate delivery and learning. This "making ready" work is essential to both flow and value delivery. Mary Gorman and i describe an technique for this in "Slicing Requirements for Agile Success" (

Views to Agile Requirements

There will continue to be a debate between what to use to represent and chunk requirements (e.g. MMFs, Features, Epics, User Stories, Story Maps, Scenarios, User Stories, etc.). Whatever mechanisms are chosen, so long as the project community as agreement on the vision, scope, domain terms (e.g. glossary) and can work at different levels of granularity...that's goodness.

I like to think of the "big-view", "pre-view" and "now-view" of requirements and have written about it in "A View to Agile Requirements" ( and, as it fits within the context of collaborative workshops ("Agile Requirements by Collaboration" at

Agile Documentation in Regulated Environment

Regarding agile documentation/SRS in regulated environments: we've worked on numerous such projects. The key is traceablity. using lightweight user requirements traced to UATs (or BDD/GWT, scenarios and the like) is lean indeed.

Two patterns i've noticed (and this includes on regulated products that are innovative): 1. build the (lightest possible) documentation as you go, or 2 later in a pre-release (also called 'hardening' or 'deployment' iteration).

Personally, i perfer including necessary documentation part of the acceptance criteria for each delivered, "done" requirement. necessary means we've analyzed the stakeholders of that documentation and defined the minimal possible documentation and its format that they really will use.

To prepare for documentation in a regulated environment i've found "being agile" (vs "doing agile" ) is effective. Again, the team defines what the minimal necessary but sufficient documentation we need (that may include doing some research into the regs by carefully reading them ;-), and then tests it. that is, run an iteration or release with the documentation we think will be fit for regulatory use, involve the validation analyst(s), regulator or their proxy, and learn if its' good enough.

And, the engine for agile teams and success with agile requirements? Collaboration! ;-)

with best regards,

~ ellen

Ellen Gottesdiener blog For more article on agile+analysis/requirements+collaboration, visit

Robin Oldman replied on Wed, 2010/12/01 - 4:24am

Thanks Ellen for your talk, it underlined my small and growing awareness of the real meaning of Agile. It was very valuable.


I’m sorry, but to me there seems to be a loss of focus generally on the purpose of requirements, in whatever form they take. They are the communication between the client – the Business - and the supplier - the IT Function. To communicate effectively is to form the self same picture in the heads of both the client and the supplier. To achieve this, you must use an unambiguous means of communication, and English, a ‘natural language’, just won’t cut the mustard.

You need rigour (sorry rigor) and a method of modelling the requirements that is based on formal mathematical principles. Having studied this problem for some years, we have developed a method that is formally based and is an unambiguous representation of the requirement. The method is not aimed particularly at any methodology, Agile or Waterfall, but can be used in both these environments. We don’t explicitly use stories, or English for that matter, to express the requirements.

We have identified the fundamental parameters of business requirements and have built a series of dialogues that collect aspects of these parameters and store them in a database. By creating a Theory Of Requirements we are able to define tests for the internal consistency of the requirements data. These tests operate as rules and can be applied to the requirements data at any time.

The second test is for the completeness of the requirements. The challenge here is to represent to the client the extent of what has been defined as the requirements in a way that enables them to identify anything that may be missing. We use Animation to provide a representation of the action of test data upon the requirements; this is exactly analogous to the final testing of a built system using client’s data – the User Acceptance Test, for example. The animation output shows both the data in the system and the sequence in which that data flows through the system. Study of this detail invariably reveals errors and omissions in the requirements, initiating an update iteration.

Both completeness and consistency testing can be undertaken at any time, making this an ideal Agile tool.

Having achieved a very high confidence in the requirements, the method and its toolkit is able to generate running code directly from the requirements. Testing the resulting code with the animation data will produce exactly the results obtained in the animation tests. Code generation takes a matter of minutes.

We call the method and toolkit SPECIFY4IT from Precision Design Technology Ltd.

There is more information at


Emma Watson replied on Fri, 2012/03/30 - 5:11am

Totally agree with the transient nature of Stories. !

I think the problem lies in- we end up looking for the same "comfort" of detailed specs. And stories aren't meant to offer that. They are there to ignite conversations. Details (if needed) should exist elsewhere. "Executable" requirements seems very exciting.

Please let me know when you have demo-able cucumber requirements. Will be interesting to see how you are doing this.


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.