Maybe it was that southern drawl.
Or maybe it was because I got mad.
I'm not sure why I still remember this moment so
clearly, but I do. It happened when I was at Spyglass, over ten years ago.
Several of us developers were in a meeting with Steve Stone, then
recently-hired as director of the Champaign office. We were talking about a
possible new feature. Steve, in his Alabama accent, asked,
"So is that a requirement?"
A couple years later, I realized that I misunderstood the
question. I didn't have enough project management background to know the
particular way that he was using the word "requirement". For me at the time,
the word "requirement" had connotations of absolute necessity. So when Steve
asked the question, here is what I heard:
"So is this feature something that
absolutely must be in the next release of the product?"
On top of that, I'll confess I was sort of generally crabby
at that point in my life, especially with respect to Steve Stone. Instead of
promoting me or one of the other lead developers to run the Champaign office,
Spyglass had hired Steve from the outside. In fact, Spyglass asked me to interview
Steve, but only after the interview did they tell me I had actually been
interviewing my new boss.
Anyway, I was in a generally foul mood when I misunderstood
this question. I suppose that's why I answered Steve by saying something like
"How the @%$* should I know if this
feature has to be in the product or not? You're new here, so let me explain
how things go. Management moved the headquarters to Chicago after years of
promising that they never would. Here in Champaign, nobody tells us anything.
We've got no marketing people except the team who spent 3 months deciding which
Pantone color is the right shade of red for our company logo, which nobody ever
sees because our product is an OEM component. The only way we ever know that a
feature absolutely must be in the product is when one of our Sales Guys calls
up and tells us that he already promised it."
Steve was a very patient man. I assume anybody who lived in
Alabama would have to be. :-) He just smiled as he listened to my
rant (footnote 1).
But my career with Spyglass didn't last too much longer
after that. A few months later, in a moment when I was ready to throw another
tantrum, I decided to just quit instead.
And I went out on my own and founded SourceGear. We started
out doing contracting projects. One of our first clients asked me for a
Software Requirements Specification (SRS) and a Traceability Matrix. That wasn't
a very good day.
But not long after that, I learned what the word
"requirement" means when used in the context of software project management.
And I learned what Steve Stone had really meant when he
asked that infuriating question. When Steve said:
"So is that a requirement?"
What he was really asking was:
"So it sounds like we just
identified something that should become part of our spec. You guys have a spec
around here somewhere, right? Who is responsible for updating that spec to
capture this new item?"
What is a Requirement?
I define a requirement as "one piece of a spec". Is that
definition complete and immune to attack? No, but I think it's the simplest
definition that works.
Of course, it relies on the definition of a "spec", so let's
What is a Spec?
A spec is short for "specification". A spec is something
that describes what a piece of software should do.
For the moment I am being deliberately broad and inclusive.
If you are experienced in software project management, you probably have something
very specific in mind when think of the words "spec" or "requirement". In
fact, it is possible that you are not willing to acknowledge that something is
a spec unless it matches up fairly well with your image of same. That's okay.
Just stay with me.
For now, I'm saying that anything that is a "description of
what a piece of software should do" can be considered a spec. This may
- A document
- A bunch of 3x5 note cards
- A spreadsheet containing a list of features
I am currently involved in a project where my role is "The
Walking Spec". In other words, I am the person who mostly knows everything
about how this piece of software should mostly behave. When people need a
spec, they ask me a question (footnote 2). I'm not saying that I am a good
spec, but I don't think I'm the worst spec I have ever seen, and I am certainly
better that no spec at all. :-)
Seriously, a spec needs to be in a form which is accessible
to more than one person. It needs to be written down, either in a computer or
Document or Database?
There is a constant tension over the form of a spec. Should
it be a document or a database?
I'm using the words "document" and "database" as names for
the two extremes which create this tension.
- When a spec is more like a document, it looks like a bunch
of paragraphs and prose and pictures.
- When a spec is more like a database, it looks like a bunch
of bullets and lists and outlines.
When a spec is being written, it wants to be a document.
It's easier to describe what a piece of software should do when we can use
paragraphs and prose and formatting.
Maybe this is because the primary content of a spec is
usually coming from someone other than a developer. We developers sometimes
write apps for ourselves, but that's not the common case. More often, we're
writing software that somebody else wants. We don't know how the software
should behave. They do. In order for the software to be born, they need to
express to us everything they know about what the software should do. That
expression is a spec.
And in all likelihood, that expression is more naturally
going to be like a document and less like a database. The person will want to
tell stories and give examples and rationale. They may want to include pictures
or video to explain.
But right after a spec is written, a document is usually the
wrong form. It started out as a document only because that form was most
convenient for the author. But a document is not the most convenient form for
the people who are reading or using the spec, and those people have the author
outnumbered. Most of those readers/users want that spec to be a database
instead of a document.
They want the spec to be logically broken up into a bunch of
little pieces. Each piece should be a self-contained statement about one
single detail of how the software should behave.
Breaking a spec into little pieces allows us to use that
spec more effectively. We can more easily divide the software construction
tasks across a team by assigning different pieces to different people. We can
then print the pieces as a list, put boxes to the left of each one and use it
as a checklist to make sure we're getting everything done.
So, let's return to the original question. What is a
A requirement is a piece of a spec. When we take a spec and
put it into its more useful form by breaking it into bite-sized pieces, each of
those pieces is a requirement.
If you are in the habit of ignoring specs, you can ignore
requirements in exactly the same way. They're no different. :-)
"Dad, where do products come from?"
"Well, son, when a company and a market segment really
love each other, they..."
Every software product starts out as a gleam in the eye of some
guy who wants to make money. He sees a bunch of people who have money. He
pauses to reflect upon how much nicer life would be if that money were moved from
their wallets into his own.
So, he pursues a process which involves the following two
- Find an idea for a product
- Build that product
Things usually fall apart between steps 1 and 2, mostly
because these two steps are done by different people. The product is not being
built by the same person who had the idea and the gleam. Step 1 is usually
somebody in marketing. Step 2 is a team of developers.
So, in order for the developers to know what product to
build and how, we need to describe it to them (via a spec) with lots of details
Construction and Testing
With a well-written requirements spec, the development of a
software project is easy.
Let's assume the project starts out with a spec that is:
- Complete. The spec describes everything the
product needs to do. Nothing was forgotten.
- Stable. The spec isn't in flux. It's not going to
change along the way.
- List-oriented. The spec is like a database; each
item being a self-contained requirement. All the prose has been
appropriately broken up into little pieces.
This is the dream scenario for a development manager.
Translate all the requirements into a set of tasks. Divide up all the tasks
between the developers on the team. How hard can that be?
Similarly, the testing lead has a very straightforward path
with this kind of a requirements spec. For every requirement, create one or
more tests that can be used to verify that the software meets that
requirement. Automate as many of those tests as possible. Every time the
developers create a new build, run the tests and report what happened. Easy,
Unfortunately, projects don't always work that way.
In fact, projects almost never work that way, because most
requirements specs are badly written.
A bad requirements spec is considerably more likely than a
perfect one. Certain kinds of problems are common.
For example, let's suppose we are building a game which is
designed to be played by middle school girls in a library. The following
examples show some typical problems with requirements:
Very often, the spec simply isn't
complete. Somebody forgot to include an important detail.
For example, since we know the game
is supposed to be played in libraries, users will need to turn the sound down
or off. So we need the game to be playable without sound. If we forget to
mention this requirement specifically, there's a decent chance the dev team
will create a game where sound is important to game play.
Sometimes requirements are
ambiguous. Here's an unclear requirement:
The game must be compatible with DirectX.
Which version? Can we use DirectX
10, thus requiring Windows Vista? Or should we target DirectX 9 and stay
compatible with Windows XP? It's not clear.
A good requirements spec contains
priority information to help the dev team make the right tradeoffs. If some
requirements are more important than others, the spec should say so.
Consider these two requirements:
The user must be allowed to save a game in progress and resume it
The main character in the game must resemble Dakota Fanning
without looking exactly like her.
The schedule is getting tight.
Only one of these two features is going to make it. Do you want to leave this
choice entirely up to the dev team? Or do you want to make it clear that
save/load is a more important feature than making the main character resemble a
certain child actress? (footnote 3)
Sometimes the problem is that the
development team tries to go above and beyond the call of duty and sneak
something in that wasn't part of the spec. This can be a good thing, but it
can also be a bad thing. A good requirements spec will contain "anti-requirements",
explicitly spelling out things that should not be done. For example:
This game must not have a grenade launcher.
Believe me, if you leave too much
latitude on a game project like this, we developers will turn it into a first
person shooter. Yes, we can see from the spec that the target customer is a 12
year old girl playing in a library. But still, our intuition is that all games
need a grenade launcher, so you're gonna get one if you don't explicitly tell
If a project gets all the way to completion with bad
requirements, the likelihood is that the software will be disappointing. When
this happens, the resulting assignment-of-blame exercise can be fun to watch.
From a safe distance.
More often, during the project somebody notices a problem
with the requirements and changes them along the way.
the way, I forgot to mention that the application has to be compatible with
95? You're kidding, right? People stopped using Win95 over a decade ago!
and Mac OS 7.6 too.
We're building this app with .NET 3.0 and we're already 40% done!
half done? That's great! Oh, and I forgot to mention we need compatibility
with the Atari ST.
didn't you tell us this before we started?
I forgot. It's no problem to change it now, right?
Changing requirements mid-project can be expensive and
However, it is very rare to have a project where all the
requirements are known and properly expressed before development begins. So,
it behooves us to prepare for changes. If we choose a development process which
rigidly requires a perfect spec before construction can begin, we are just
setting ourselves up for pain. We need to be a bit more agile.
I lament the loss of the word "agile".
A minute ago when I used the word "agile", most readers
immediately thought I was talking about Agile software
development practices such as Scrum or Extreme Programming. That means
your reaction was probably polarized toward one of the following two extremes:
- Oh, great! I'm five pages into this article and suddenly
I find out Eric Sink is one of those Extreme Programming fanatics? I
guess that's 15 minutes of my life I'll never get back. Sorry, I don't
mind visiting once in a while like on Christmas or Easter, but I'm just
not interested in having somebody tell me how to live my life. And I
don't want some Agile priest telling me that I'm not a true believer just
because we don't do pair programming.
- Oh, great! Here's Eric Sink trying to pretend like he's a
believer when everybody knows he's not. Actually I guess I should check
the Central Membership Roll just to be sure. Nope, I was right. He's
not. Even if he was, we would have to excommunicate him anyway. Anybody
who reads the drivel on his blog knows darn well that his doctrine is
seriously screwed up.
I just want to use the word "agile" without all those
connotations. My copy of Merriam Webster's Tenth Edition says that "agile"
means "marked by ready ability to move with quick easy grace". At a high
level, that's all I'm trying to say. Sometimes requirements change. Be ready.
In more practical terms, I'll admit that the body of wisdom
literature produced by the Agile movement has some very good stuff in it. But
Agile is no different from any other major religion like Christianity or
Buddhism. You can learn some great principles and practices there, but
formally becoming a member is a decision that should not be made lightly.
I've tried to write this article at a fairly high level,
focusing more on principles than practices, staying inclusive of the broad
range of viable methods for getting projects done. However, the truth is that
the word "requirement" is usually associated with stricter and more formal ways
of doing things.
We developers say that we don't like formality and
strictness, but I think we're confused.
We don't like being told what to do. We don't like stupid
rules that don't make sense. We don't like working for some stupid
pointy-haired-boss who draws arbitrary boundaries that we're not allowed to
But we spend our entire day using a compiler, and compilers
are very formal and strict. In C, if we type primtf
instead of printf, the compiler
will let us go no further until we stop and fix it. In C#, if we try to use an
uninitialized local variable, our compiler will scold us for stepping outside
Do we go out after work and gripe about our compiler?
"I am sick and tired of that stupid
compiler! When I do something right it never says a word, but if I do the
slightest little thing wrong, it throws a fit. Why does it have to nitpick
about every little mistake I make?"
Nope. Actually, we like compilers. We like the formality
and strictness. We know having a compiler to catch our mistakes is a good
thing because it allows us to go faster. It's safe to sit down and crank out a
thousand lines of code as fast as we can because we know the compiler will find
a lot of the little errors that happen.
Wouldn't it be great if every phase of the software
development process had a compiler?
- I want a piece of software that tells me if I forget to
implement one of the requirements.
- When my requirements conflict with each other, my "spec
compiler" should output an error.
- When one of my requirements isn't being verified by
anything in the test suite, some piece of software should tell me.
The compiler I want doesn't exist today, but there are
things we can do to approximate that style of work. For example, code coverage can be
used to help verify that things are getting tested. Automated testing can help
catch bugs that slip in.
The concept which may eventually get us the compiler I want
is called "traceability". The idea is that everything should be traceable back
to something else.
- Every piece of code in the project should exist because it
helps meet one or more requirements. Traceability should allow us to ask,
"Which requirement motivates this piece of code?" If the answer is
"none", then that piece of code should be excised.
- Every requirement needs to be tested. Traceability should
allow us to ask, "Which tests verify that this requirement is being met?"
If the answer is "none", then we need to write some more tests.
Lacking my super-duper application lifecycle compiler that
verifies that everything is traceable, we can keep track of some of this stuff
using a traceability
When it functions more like a compiler than a pointy-haired-boss,
a little extra formality and strictness can be very helpful.
Requirements Management Software
Naturally, we want to use software to manage our
requirements. Many folks do this with a general-purpose tool like a word
processor or a spreadsheet. That works fine.
Some people track requirements in a bug-tracking system.
This can work, but it's not a perfect solution. Requirements and bugs are
different. For example, requirements don't change status from Open to Closed
Another approach is to use something which is specifically
designed to track requirements. Application Lifecycle Management (ALM)
software often contains features for managing and tracking requirements. The
ALM solutions from companies like IBM Rational, Serena and Borland are
examples, but it should be noted that these solutions are very expensive and
designed for large enterprise environments.
My own company will soon be releasing an ALM solution which
is designed specifically for smaller teams. We call it SourceGear Fortress.
However, the 1.0 release will not have any features specifically designed for
tracking requirements. We do intend to include this and other features in the
future as we evolve Fortress into a mature and complete ALM solution.
Microsoft made a similar choice with Visual Studio Team
System. However, since their product is enterprise-focused, it has been
criticized for not having any requirements features in the first release
(footnote 4). I suspect that this is a hole they plan to plug at some point in
This short article barely scratches the surface of a very
complex topic. For additional information, I recommend the book Software
Requirements by Karl E. Wiegers.
(1) I have no hard feelings toward my old
boss at Spyglass. I lost touch with Steve Stone, but I understand he later
left the company and joined Microsoft. A little searching with Google reveals
that he is currently the CEO of a startup company called InfoFlows. Steve, if you are reading this
article, best regards.
(2) Rest assured that this project is not
one of SourceGear's products. It's a revision to one of our internal systems.
(3) Hypothetically, the reason this save
feature might be so important is to ensure that when the hypothetical father of
the hypothetical middle school girl arrives at the hypothetical library to pick
her up, she can save her game and go promptly so her Dad doesn't have to wait.
(4) Third-party products are available to
add requirements management features to VSTS.