Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

4 Answers 4

up vote 8 down vote accepted

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.

share|improve this answer
    
Thanks for links, it's very helpful! I think i had misunderstood McConnell. I thought it should be separate item in requirements, like "success is ...", but as i see now, it's kind of quality of each requirement. –  AlexLocust Oct 26 '11 at 19:33
    
@AlexLocust That's correct, however it doesn't necessarily need to be stated like that. Saying "The system shall have a downtime of no more than 4 hours per year" is correct as well - success is building a system with reliability and maintainability characteristics such that it can remain up for all but 4 hours of the year. –  Thomas Owens Oct 26 '11 at 20:10

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

share|improve this answer
    
+1 Exactly. Its all about being able to show that it does what it is supposed to do and does not do the things it is not supposed to do. It sets criteria for evaluation of that. –  Chad Oct 26 '11 at 18:29

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.

share|improve this answer
    
This is a good point and ideally testing demonstrates the qualities outlined in @Thomas_Owens' answer -- "Code's not done 'till all the tests run!" –  Michael Oct 27 '11 at 13:21

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.