Why it is important to include definition of success/failure in specification?

Question

I've read Steve McConnell's "Code Complete" and one of items in checklist for requirements is: "Is the definition of success included? Of failure?".

Why is this important? Can you write any examples of those definitions? Can anybody provide examples of good requirements specification?

Answer 1

Why it's important? Can you write any examples of those definitions?

When you specify a requirement, it's important that it meets certain qualities, such as cohesiveness (only address a single thing), complete (does not lack any information needed to fulfill the desired outcome), traceable (it is documented and can be tracked through design, implementation, and maintenance in both directions), up-to-date, feasible (it can actually be implemented), unambiguous (multiple people reading it will have the same idea of the desired outcome), and verifiable (it can be tested and easily seen whether the requirement is complete).

Defining success or failure criteria for a requirement allows it to be complete, traceable, feasible, unambiguous, and verifiable. How can you know if the requirement can be met now or in the future? How can you know when you have implemented the feature or aspect of the system? How can you point to specific modules at any level that implement the requirement, either in a representation of the design or the implementation?

This is somewhat related to the concept of "definition of done" in the agile community, as well.

Can anybody provide examples of good requirements specification?

You can find a lot of information about requirements, including examples, in Karl Wiegers' Software Requirements and More About Software Requirements: Thorny Issues and Practical Advice. In addition, Wiegers' site Process Impact provides a number of goodies, such as sample documents and templates.

Answer 2

"Complete" implies "does not need a couple more hours/days/weeks/months fussing about it until it's perfect". It's hard to know when to move on to the next thing in the pile if you never know when you're done - which requires knowing exactly what "done" is. (And moving to the next thing is a good thing because that's how you end up delivering what you promised).

It is actually very hard to describe exactly what's needed for something to be "complete" - but having a list of success (if it doesn't do that it isn't complete) and failure (if it does that it fails) is a good way to get there.

Answer 3

A good requirement is something that is by its very nature Testable. The requirement itself defines its own metric of success or failure, was the requirement met or not?

There may be 1...n test cases for a single requirement but if the requirement is ambiguous, subjective, or conjunctive (combining multiple requirements using conjunctions) then it is no longer Testable.

Success or Failure are attributes one would apply to a Test Case for a requirement not the requirement itself.

The System shall display an error alert to the user if the credential job queue contains 80% or more un-audited documents.

Answer 4

We just started using scrum, so this idea of having a definition of done is new to us, but has been very useful. For just one example, we had a user story to get a build compilable. It seems apparent what that means, but having a definition spelled out really helped us. One part of that definition was to have another developer check it out from source control and verify it compiled without errors or warnings from a clean build. That caught a problem where I forgot to add some files in source control, so it built on my machine but not others.

Other things that came up were what should be included in the build for it to be called "done." Can we temporarily leave out modules with a lot of compile errors that are time consuming to reconcile? That led to a discussion about what we really need it for at this point in our development cycle. Without that discussion, we might either wait too long for a "perfect" build, or erroneously call a build done that is completely unusable by the rest of the team.

In other words, a definition of success makes sure we all know what to expect and what not to expect when we are finished. If it makes a difference in something as simple as compiling a build at the start of a project, it will make that much more of a difference on requirements the customer really cares about.