Software Requirements

Karl Eugene Wiegers

Mentioned 12

Describes techniques for the requirements engineering process through the entire development process.

More on Amazon.com

Mentioned in questions and answers.

I was wondering if anyone could provide me some information on what they put in a requirements document, how do you structure it? I'm the lead for the first time ever and I want to make sure I provide good documents so the project will succeed.

Any templates/examples would be great.

This is a somewhat deep question, so I am hesitant to give a short answer. It is a good idea to read a few good books that describe different approaches, such as The Inmates Are Running the Asylum, which describes scenario-based function design. Another approach is to use high-level use-cases, as described in Writing Effective Use Cases.

Some guidelines:

  • Write what is required without constraining how this will be done.
  • Make each requirement a separate numbered list entry for cross-reference.
  • Split requirements into separate items until each one is 'atomic'.
  • Include a Security section, and be explicit about what security is required.
  • Include a Non-functional requirements section, for constraints like performance and availability.
  • Include a Non-requirements section to list things that are not requirements, so you can tell the difference between something you forgot, and something you do not need.
  • Specify external interfaces (to other systems) as well as user-interface requirements.

Karl Wiegers, author of Software Requirements and More About Software Requirements also has a website called Process Impact. Although most of the stuff is for sale, you should check out the Goodies section, which has documents that are released for the nominal sum of $5. One of the files that you can download is a set of Sample requirements documents, including a vision and scope document, use cases, software requirements specification (SRS), business rules, data dictionary, and some analysis models for a small information system (ZIP file). You can also find templates for a number of requirements documents.

If you have the money, I would recommend both books. If you don't want them, maybe your company can buy and own them if there is a company library or something like that. Either way, they are must-reads for anyone working on requirements gathering/analysis.

So basically I am looking for good templates for writing both technical and functional specs on a project or work request.

What do you use? How deep do you get while writing the specs? Any additional general tips you could provide would be appreciated.

My company needs these badly. I work for a contractor and right now we do not use these documents at all.

EDIT: I have read Joel's take about Painless Specification, I really liked it, but are there any other opinions :)

If you want to purchase a book, Software Requirements by Karl Wiegers has templates for a few documents as an appendix. Unfortunately, I'm at work and that particular book is at home. If someone has it handy, they might be able to confirm that.

You can buy templates from ieee and other places, but I have always ended up making my own.

For a technical spec, "Code Complete" by Steve McDonnell has a good checklist, you can draw some info from that. At my last job, I just made a template out of his section headers, and tweaked it from there.

As far as a functional spec, the important thing is to define all the interfaces:

  1. UI (screen mockups)
  2. Software interfaces (plugins, etc.)
  3. Hardware interfaces (if appropriate)
  4. Communications interfaces (Services, email, messaging, etc.)

There should also be a section for business rules, things that are important functionally that are not covered in any interface definition.

How do you go about the requirements gathering phase? Does anyone have a good set of guidelines or tips to follow? What are some good questions to ask the stakeholders?

I am currently working on a new project and there are a lot of unknowns. I am in the process of coming up with a list of questions to ask the stakeholders. However I cant help but to feel that I am missing something or forgetting to ask a critical question.

Requirements Engineering is a bit of an art, there are lots of different ways to go about it, you really have to tailor it to your project and the stakeholders involved. A good place to start is with Requirements Engineering by Karl Wiegers:

http://www.amazon.com/Software-Requirements-Second-Pro-Best-Practices/dp/0735618798/ref=pd_bbs_sr_2?ie=UTF8&s=books&qid=1234910330&sr=8-2

and a requirements engineering process which may consist of a number of steps e.g.:

  • Elicitation - for the basis for discussion with the business
  • Analysis and Description - a technical description for the purpose of the developers
  • Elaboration, Clarification, Verification and Negotiation - further refinement of the requirements

Also, there are a number of ways of documenting the requirements (Use Cases, Prototypes, Specifications, Modelling Languages). Each have their advantages and disadvantages. For example prototypes are very good for elicitation of ideas from the business and discussion of ideas.

I generally find that writing a set of use cases and including wireframe prototypes works well to identify an initial set of requirements. From that point it's a continual process of working with technical people and business people to further clarify and elaborate on the requirements. Keeping track of what was initially agreed and tracking additional requirements are essential to avoid scope creep. Negotiation plays a bit part here also between the various parties as per the Broken Iron Triangle (http://www.ambysoft.com/essays/brokenTriangle.html).

We have a project hand over from on shore team to our team (off shore) not long ago. However we were having difficulties for the hand-over process.

  1. We couldn't think of any questions to ask during their design walk-through, because we were overwhelmed by the sheer amount of information. We wanted to ask, but we didn't know what to ask. Since they got no question from us, the management think that the hand-over process was been done successfully.

  2. We had tried to go through all the documentation from our company wiki page before attending the handover presentation, but there are too many documents, we don't even know where to start with.

I wonder, are there any rules or best practices that we can follow, to ensure a successful project hand-over, either from us, or to us.

Thanks.

Check out "Software Requirements" and Software Requirement Patterns for ideas on questions to ask when gathering information about a project. I think that just as they would work for new development, they would also help you to come to terms with an existing project.

I recently read through Code Complete, and it recommends that I create a project specification before actually coding.

The book didn't go very far into detail about what 'specs' are, and how they are made. Because this is a crucial part of software development, I would like to know how to create quality specs that are not too exhaustive.

Where can I learn more about software specifications? Or any of the other prerequisites outlined in Code Complete?

If you are looking for books, I can recommend two right now, and in fact, I ordered a third because it looked good.

The two I can recommend fully are:

I also ordered a third book:

How to collect system engineering or product requirements? For example, if we want to make a car, how should we collect the requirements? Kindly guide me.

I would probably start off by readying Gathering Requirements I would then checkout Joel On Software and 37Signals. They have decent information regarding creating requirements documents. The Joel on Software site has an example of one.

Please suggest material regarding the best practices for writing design documents.

This article on Writing Quality Requirements would probably be worth the read. The end of the article has some general "Guidelines" that would probably be useful to you.

Among the guidelines are things like:

  • Keep sentences and paragraphs short
  • Use the active voice
  • Find the right level of granularity (requirements written should be individually testable)
  • Avoid writing multiple requirements in a single statement (conjunctions like "and" and "or" can help you spot this)

Lots of other good resources similar to the above article are available to help give you some perspective. If you're looking for a much more comprehensive look at requirements "best practices", check out Software Requirements, Second Edition (Amazon).

I also have to recommend not only the book that Donut suggested in his last sentence, Software Requirements (2nd Edition), but also a companion to that book - More About Software Requirements. Both books are by Karl Wiegers, and his website has some interesting reading as well, in particular the Goodies section, which has freeware sample documents and templates.

Good morning everyone,

I hope I'm not posting this in the wrong place; I've been programming web projects, mostly in MVC and ASP.NET for consulting companies, but I always pick-up unfinished projects, so I gotta say, my experience in web development isn't as good as I'd like it to be. To improve my experience, I decided to accept building a project for a veterinarian clinic and I'm going to build the project in MVC. There are a few things I'd like to know to make my project well structured and to avoid feeling lost in the process because I don't have as much time to research as I'd like to. So the main questions I'd like to ask are:

  • When beginning a new project, where should I begin? Making the stylesheets? Should I go straight for the code? If I make some planning, how should I go about it then?

  • When building up the Media folder in my project, if I decide I'll use
    jQuery and the like, what files
    should I really get? What's the best way to implement jQuery in a MVC
    project without having to mention it in every page?

  • To make a sort of planning for
    myself, complete with deadlines I
    have to respect, what structure
    should I use?

  • Well, I'm not good at designing at
    all, and I often have to rely on
    other people's CSS to make things
    look decent, so how could I use this project to improve that and still
    make it look good?

I hope we can all share some experience in the matter at hand and make this topic help others who might be feeling the same weaknesses as I do.

When you start building your code I suggest you start with register, login and authentication. After that: Internationalization and localization (see: http://en.wikipedia.org/wiki/Internationalization_and_localization)

Then create your CRUD's and so on..

EDIT: Some other resources you might wanna have a look at:

Good luck!!

How to write a vision [generally] for some business ? Is it have some template ? any example ? Business about online ticket services .

Karl Wiegers' book, Software Requirements, has an excellent template. I've used in for several projects. It seems a bit formulaic at first, but over the subsequent days and months, really helps a team keep focus.

http://www.amazon.com/exec/obidos/ASIN/0735618798/processimpact http://www.processimpact.com/books.shtml

Let us posit a company which is doing just about as much wrong as it is possible to do with regard to software development.

Let us suppose that management, which imagines software to fall from the trees, grudgingly recognizes that there may possibly be a small problem and is finally willing to all to "try something".

The something has to be free (as in dollars) and "non-disruptive".

Basically, something for nothing. If you choose right it won't be mentioned at your next performance review (because the dear leader will take the credit), but you may have the privilege of suggesting a second "something" to "try" (of course, if you choose wrongly, management will shoot a puppy and drown a kitten and the whole thing will become more of a Yourdon-death-march than it already is).

Choose wisely, for you only have one choice. What single tool, Process, anything, will have the most bang, preferably in the least time, for the least buck.

And to anyone thinking of deleting this as being too subjective, I can only say, "you lucky offspring-of-unwed-parents, your fellow developers and project managers around the world are in this very situation even as you reach for the "delete" button".

Unfortunately there are a huge number of ways things can suck. So I'll start at the top.

Most projects fail due to poor requirements gathering and specification. Insist on no new code without proper specs. These do not need to be ridiculously detailed waterfall artifacts that are never looked at -- but at a minimum, you need to know:

  • Why is the feature needed? (a quick history or summary of the problem being solved)
  • What will success look like? (a summary of expected behavior)

Then you reply with a document that looks like this:

  • It looks like you want me to write something that does (what they said in their document).
  • To accomplish this, I propose these changes to the existing code.

Send that back and get them to agree that it sounds good. They will because they have no clue what you do and they trust that you do.

Then, and only then, start talking about how long it will take to do this. The conversation, hopefully, will go like this:

  • The right way to do it will take me a month.
  • What, you wanted it in a week? OK, well, I can get you 70% of what's in this spec if we make this small change. This last feature is really hard, even though it looks like we're just changing the font to comic sans...

Now you've gone from management hating your guts for not working miracles to having them understand -- before you start coding -- what kinds of things are holding back success.

The next best thing is dedicated QA resources and a good bug tracking system, though they cost money (though Joel would say that they cost a lot less than programmers doing testing!).

I agree with others that unit tests are an important part of maturing your code, but they are useless if your problem is poor requirements.

===

Quick edit for a book recommendation: http://www.amazon.com/Software-Requirements-Techniques-Throughout-Development/dp/0735618798

I'm a web application developer looking for a book or something similar that can help with effectively communicating with clients who have a very vague or unrealistic idea of what they'd like out of the work I'm doing.

Some fictional, though not by much, examples of situations:

  • Clients who are not familiar with using the Internet, and insist on features that are not even remotely feasible (ex. time travel)

  • Clients who are unable to express accurately what they're looking for (ex. "I know that's what I said and signed off on, but it's not what I meant")

  • Clients who refuse to attend meetings or review sessions to answer questions or define requirements (which makes any agile development impossible)

For the most part, I'm trying to find best practices for how to handle these kinds of things on a team-building level. The best ways to effectively address serious project roadblocks without sounding like a total jerk.

Any recommendations for reading material on this topic?

I can sympathize...you're struggling with issues I think every software project does at some point or another. But time machine? Wow, if only. Though I don't know if having one would make things better or worse!

Karl Weigers has some good books on requirements.

Software Requirements: Practical Techniques for Gathering and Managing Requirements Throughout the Product Development Cycle.

A follow up he wrote called More About Software Requirements: Thorny Issues and Practical Advice is also good and tries to address common roadblocks.

Agilists, of course, will note that you can trigger more earnest feedback from users by showing them something earlier in the process, even a crude prototype.