A story on specification by example in two projects

· August 22, 2010

The last month I’ve read The Goal by Eliyahu M. Goldratt. Apart from being a great book it was also written in a really interesting way. It’s a novel in which we follow mr Alex Rogo and how he learns the subject of the book Theory of Constraints. I thought that I might try to mimic that style a bit in this post.

The subject I’m getting back to again and again nowadays is agile for the whole project. In my opinion agile thoughts often come from development and never gets a good foothold in the analysis/requirements or in the testing departments. “Yes, by all means… Do this agile you like so much but please let us write the specs and test cases as we always have done.” – is a common reasoning where I’ve been.

OK – on to the story. It comes in two flavors, set in in two different companies; Waterfalling Inc. and Agilement Corp.  They are in the same place in their project – about to start development and we will see two different approaches to tackle that. Let’s visit Waterfalling Inc. first.

And yes, the names, persons and events in this story are all fictional and just freak of my own imagination…

Waterfalling Inc

Sven is rushing. He has called this meeting with the tester in charge for the project, Johan, AND Marcus – the solution architect. Just to get hold of an hour where they wasn’t booked wasn’t easy but to then be late will not improve the meeting climate. Sven swipes into the small room just in time to see Johan and Marcus take their seats. Great – he made it.

“Well I’m happy that we’ve finally reached this point” - Sven starts, and continues: ”As you might know or not, we have been slaving away for quite some time on this project here at the requirements department”.

Johan and Marcus looks tried. They look at each other with a kind of here-we-go-again-face.

“Yes, just to get hold of these users are often very hard. They are so busy. This system will really help them I hope. Would have been great to meet them more, but two half-day workshops was all they could spare” - Sven explains. ”Any-who… now we have compiled their thoughts and understanding of the current system into, if I can say it myself, quite a impressive requirements document. It 400 pages worth!”. Was that a small whistling Sven heard from Marcus?

After a moments silence Johan cuts in: ”Well we in the test team haven’t been sleeping either. We sat in on the first meeting with the customer and then went on to book meeting of our own. With the first draft of the use cases in hand we have created a whole lot of test cases. There is a lot of different paths to cover in this system, you know”

Sven interrupts: “Which users did you meet with? Anders and Cilla?” ”No, it was Gunilla and Madde actually” – Johan replies, “but they work with the same thing, don’t they?” ”Yeah, I’m sure they are in tune with each other.”, Sven says.

Finally it’s Marcus turn. How often is this part neglected, he thinks. If you don’t think these IT-things and early decisions through they will become a mess later on. “And for our part, the technical side of things, we have also been doing important stuff. There’s a lot of technical and architectural stuff that needs to be decided long before any code is actually written.” - he states with small amount of professor in his tone.

Seeing that he has caught their attention he continues: ”For example, the architectural standards that we need to adhere here at the company, naming convention and the layering of the system. We have actually implemented a first run through of the all the layers in the application that will serve as an example. Nothing we will use in the real system but just for trying stuff out. “

“With that in hand we can safely pass all of the reviews that the IT-department makes us go through. That has been the goal for our work so far…”

“Well then, “ Sven try to stop Marcus before this turns in to techno-babble “ do you think you can build the system from these requirements? And the obligatory question – When is it done?”

Marcus: “I cannot see any problems here… You guys seems to have thought of everything.Just the amount of pages before me is testament alone to that.” ”As for the estimate – I’d say three months… five at most. Not counting testing and bug fixing of course”.

Sven looks at Johan who responds; “No but we often calculate just the developing time divided with PI, which gives us about a month to test this.”

Sven concludes the meeting: “It sounds about right. Lets finally start creating the system! And hey, Good luck!”

Agilement Corp

Steve is rushing. He has called this meeting with John and Mark and he knows that they both just arrived to the project. Steve wants to make a first good impression. He even bought cookies for the meeting. As he enters the team room he sees John and Mark on their way back from the coffee machine.

“OK – guys want to sit down to discuss our initial thoughts on how to tackle this system.” ”I rather stand in front of a whiteboard – easier to visualize my thought there”, John suggests. “Great idea” it comes back almost in unison from Steve and Mark.

Steve starts; “Ok, we have now interviewed the users of the application and got a pretty good idea on what they need. Unfortunately they will not be able to be part of our team. But they have promised to put one or two people to our disposal an hour a day. So we’ll have to batch up our questions for a day. We thought that it was acceptable. What’s your thoughts?”

“If that what they have – that’s what we’ll have to accept.”, Mark injects.

“OK”, Steve continues, “ for starters I think that the team that has done the interviews will do just fine. And then we’ll use the customer hour each day to check back with them”.

“So how do we do this then?” – Steve put the question out.

“Let’s try to specify the system with acceptance criteria’s”, John calls out… a bit too loud maybe. “It was something I read about a time ago that sounded very interesting I thought.” ”The whole idea is that you start out from a user story as we usually do but then you write down some example scenarios that in essence is the acceptance criteria’s for that user story. For example from a great blog post by Dan North

John walks up to the board and write the following down:

Story: Account Holder withdraws cash

As an Account HolderI want to withdraw cash from an ATMSo that I can get money when the bank is closed

Scenario 1: Account has sufficient fundsGiven the account balance is \$100  And the card is valid  And the machine contains enough moneyWhen the Account Holder requests \$20Then the ATM should dispense \$20  And the account balance should be \$80  And the card should be returned

“Alright – now we’re talking” – Mark joins in. “That will become both our specification to code against and our acceptance criteria for verifying the feature afterward.” “And regression test as the system grows” – John adds.

“Fine, fine my young padawans! Get back to earth you two” – Steve is not yet impressed. “How do we go about creating all those user stories and scenarios? All we have now is high level feature overview. It’s nowhere near the detail level you are talking about” ”OK, but some of those features are understood at a level where we can start to create user stories from them, right?” – Mark starts. ”Yeah, I guess”, it comes reluctantly from Steve. ”And we certainly don’t want to specify the whole system at once. Now do we?” – Mark is walking dangerously close to being patronizing now.

“Well, a suggestion might be to start out with one of those feature and try to sit down and write user stories and specification for them” – Johns saves Mark from an awkward moment. And continues: “That can be done in a workshop with a team with all our three disciplines; requirement, test and development. And the final result can be double checked with the customer.”

”OK – I’m getting you now…Something like this maybe?” – Steve steps up to the whiteboard and draws the following picture:


“All disciplines that are needed to figure out how the feature is to be implemented meet up in a workshop. They all bring their understanding of the problem and any documentation they need to remember what’s been said in earlier discussions.” – Steve explains as he draws.

“Yes”, Mark injects - “and the beauty of that is that the workshop will produce a single document with the shared understanding of the problem. It’s all very DRY – Don’t repeat yourself – as any programmer would say. ” ”And! We’re creating the test cases at the same time as we are creating the specification.” – John adds. “And! It’s documented in a format that we can show and talk about with our end users. They will surely understand plain English, won’t they. No more explaining state diagrams…”

Steve adds the customer to the drawing:


They stood back for a while – very satisfied with their progress. But John, being the skeptical one of the lot wasn’t all happy. Something was nagging him. Suddenly he realized what it was: “But hey… you surely doesn’t suggest that we will write these scenarios perfectly the first time. Or even find all variants of them? Then we will just be back in a waterfall process again. Although smaller waterfalls.”

“Of course not “ – Mark said – “but then we could just add more scenarios as we develops understanding of the problem. Or as we see stuff that is needed for understanding the function. Or stuff that we won’t to test.” ”The document will be a living document that we’re working on through the course of the project or at least feature”

All of a sudden Andrea, one of the young hot-shot programmers approaches the group: ”I’m sorry – I couldn’t help but overhearing what you where talking about. I just found this tool called SpecFlow that could execute scenarios written in the syntax you have described.”

The group goes silent. Andrea continues very slowly. ”Well… I just thought that … we maybe could run those… scenarios against our daily build and … maybe… get a automatic run through on our features. As we go…” – he stops here. Was that to bold?

She soon finds out that is was not, when the three men starts to laugh and dance around her.

Steve sums it up: “Let’s call it a day! We cannot get further today I think. Drinks are on me”


And we’re back in the real world. OK, that felt quite cheesy a times, but I for one realized a lot of stuff while writing this. Actually I have been at Waterfalling in many projects. They still exists today. I promise.

The way I suggest here is one way to go and is based on the works of Dan North and Gojko Adzic and others. SpecFlow is an execellent tool to implement the suggested approach on the .NET platform.

Twitter, Facebook