Home About Eric Topics SourceGear

2007-05-14 12:47:17

Requirements

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 this:

"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 go there.

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 include:

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 on paper.

But how?

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 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 "requirement"?

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.

Corollary

If you are in the habit of ignoring specs, you can ignore requirements in exactly the same way.  They're no different.  :-)

Writing Requirements

"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 steps:

  1. Find an idea for a product
  2. 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 (requirements).

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:

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, right?

Unfortunately, projects don't always work that way.

In fact, projects almost never work that way, because most requirements specs are badly written.

Bad Requirements

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:

Missing 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.

Unclear Requirements

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.

    Non-prioritized Requirements

    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 later.
  • 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)

    Missing Anti-Requirements

    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 us otherwise.

    Changing Requirements

    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.

    Marketing:              By the way, I forgot to mention that the application has to be compatible with Windows 95.

    Development:         Windows 95?  You're kidding, right?  People stopped using Win95 over a decade ago!

    Marketing:              Oh, and Mac OS 7.6 too.

    Development:         What?  We're building this app with .NET 3.0 and we're already 40% done!

    Marketing:              You're half done?  That's great!  Oh, and I forgot to mention we need compatibility with the Atari ST.

    Development:         Why didn't you tell us this before we started?

    Marketing:              Sorry.  I forgot.  It's no problem to change it now, right?

    Changing requirements mid-project can be expensive and painful.

    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.

    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:

    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.

    :-)

    Traceability

    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 cross.

    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 the boundaries.

    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?

    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.

    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 matrix.

    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 to Verified.

    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 the future.

    Additional Reading

    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.

    Footnotes

    (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.  Hypothetically.

     (4)          Third-party products are available to add requirements management features to VSTS.

    Copyright 2001-2023 Eric Sink. All Rights Reserved

    If you are in need of contract software development services, I would appreciate your consideration of SourceGear.