More about Software Requirements

Karl Eugene Wiegers

Mentioned 4

Provides solutions to a variety of problems associated with the software 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.

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:

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.

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.