views:

5084

answers:

10

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.

+2  A: 

Well, anything could be a requirements document. Anything that describes the functionality of a Thing[tm]. Maybe you want to check out http://joelonsoftware.com/articles/fog0000000036.html for GUI based software.

EricSchaefer
I'd say anything that describes the functionality of a thing is functional specification. IMO requirements documentation describes the need rather than how the need can be met.
Shane MacLaughlin
i seeing this too - people are bluring the lines between whats a requirements document and a specification. i have used joels structure before for functional specs (its good, very good).
louism
+20  A: 

Peter Hilton made the following recommendations, and I agree they are needed:

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.

Report Template

Executive Summary:

Presents an overview of the requirements findings in a format that allows decision makers to make important decisions effectively and efficiently.

Introduction:

Introduces the major sections of the report as well as the primary people involved in conducting the requirements gathering and the techniques used in producing the report. The client is also clearly identified.

Background:

Describes any information which is needed to provide the reader with an understanding of the background, e.g., who initiated it and why.

Scope and Purpose:

Describes the scope and purpose(s) of the proposed product.

Methods and Instrumentation:

Describes the methods and techniques used such as observations and surveys. Step-by-step descriptions of what was done should be provided. Describes all the instruments and tools that were used during the requirements gathering process, and copies of the tools should be included in the Appendices.

Limitations, Questions and Issues:

Spells out any limitations and issues, also describe threats to the reliability and validity of the instruments used in requirements gathering (e.g., questionnaires, interview protocols, or focus group protocols). Precise specification of questions, issues and problems. Clarity and detail are needed to enable useful answers.

Results:

Spells out the findings. Graphs, charts and statistics should be used wherever appropriate.

Recommendations:

Presents recommendations based upon the findings

References:

Lists the sources reviewed or consulted during the analysis.

Appendices:

Additional material for clarification, extention and informational purposes.


More reference material in this answer.

slashmais
"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." -- We created a Scope section for this information. It can really help to say "Yes we know about X but we've decided it is out of scope."
Kelly French
+1  A: 

I think you first need to decide what process you might use. This could depend upon the type of project it is, size, timelines, initial verbal requirments, etc. Once you decide which process (after meeting with the client/principle/whoever its for) get a few books on that process as they will outline things you will require and how to go about it.

For example, if you go with an agile process, you may just need a few peices of paper with a few stories on it. (This is at its very simplest of course)

But if you go with a more traditional watefall approah, you will need a LOT of verty detailed requirements up front and will totally change the way you go about your requirements and planning phase.

mattlant
A: 

I'm the lead for the first time ever and I want to make sure I provide good documents so the project will succeed.

In that case the best thing to do is not to make the requirements document gold-plated, but to make it editable. It needs to be Just Barely Good Enough(TM) that you, the testers and the customers agree on what the software is, but no better; and it needs to be flexible enough that once the customers stop agreeing on what the software is you can accommodate that.

Graham Lee
+12  A: 

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.
Peter Hilton
+2  A: 

When I write a requirements specification I focus on the percieved market needs or explicit customer requirements. This is usually done in terms of the existing conditions, processes in place and environment. For example;

  • Company X sells bread to supermarkets using employess who sell and deliver bread from vans.

  • The are currently using paper dockets and would like to move to an electronic system.

  • They want this system to feed into SAP, which will automatically keep the accounts up to date and generate all the necessary paperwork for the customer.

  • The users will typically be from a weak educational background and have no computer skills, this the system must be very easy to use and easy to train.

  • The system must be quicker to use in the field than the existing paper system

  • The hardware must be rugged enough to work in a harsh environment in low light conditions. e.g. IP76, and backlit screens.

  • The cost of the system must be no more than $5k per user

etc...

Basically the requirements documentation is a record of the requirements analysis. The requirements analysis is a detailed investigation into customer needs. I personally avoid putting any functional information relating to the potential solution in at this stage, as I like to keep requirements and implementation seperate. In a more agile environment you may well iterate through requirements and potential implementation a number of times.

Shane MacLaughlin
+7  A: 

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

Thomas Owens
+2  A: 

The Inmates Are Running the Asylum by Alan Cooper has been recommended - This great high-level book is targeted at explaining the importance of user-centered design to management and executives.

About Face 3.0 by Alan Cooper is the practitioner's guide to user-centered design and is a brilliant guide to ensuring that a product meets the needs of its users.

The best resources I'd recommend for producing requirements documents are Mastering the Requirements Process by Robertson & Robertson and Software Requirements by Soren Lauesen. the latter provides an in-depth introduction to a number of requirements gathering and capturing techniques.

Depending on the nature of your project (and your role) you might want to consider a more lightweight, agile methodology. Software requirements invariably change once they're written and agile methodologies are designed to recognise this and factor change into the software development process - producing a very lean initial set of requirements and building upon them as the project progresses. Check out Extreme Programming Explained by Kent Beck for more on this style.

If you've gone through all of this already and are just after templates the two most commonly-used (or adapted) are the IEEE standard (1220-1998) and the DoD standard MIL-STD-498. Of these the MIL standards seem (to me) to offer the most value for the least overhead - But still require a lot of effort that may not directly add value to your project.

Chris B-C
+2  A: 

If you are looking for a specific standard, you can look at IEEE 820-1998 - Software Requirements Standards. there are templates etc around if you google for them. there is even a basic template on wiki : IEEE 830 - SRS template

You might also want to look at the whole SWEBOK (Software Engineering Body of knowledge) from the IEEE.

MikeJ
A: 

Scott Ambler's "Agile Modeling" site has some good samples. There's also a lot of concise, pragmatic advice on Agile requirements in general.

Worth a look!

Tom Bushell