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
We were really suffering from some of the classic problems mentioned in Mike’s book including:
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...
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.
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.
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
and emails that involved convoluted phrases like “…but don’t you
realize that requirement 18.104.22.168.17b clearly means that in this
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
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
(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.