Software requirements documents

My company, and my department, has just recently accquired the rights to an established software program.  We have been working on sales and marketing this program for 3 years, and are now going to begin developing it.  My team is very familiar with the industry it is for, but not so with software programming.
We have been given the task of developing requirements document for the new version of the software.  The development (or programmers) team that is going to do the work has never worked on this particular program before.  We are completely rewriting the software into a different language and database.
Enough history...what I need to know is:  Is there a standard format for requirements documentation?  And, if not, can some folks with more experience with this give us some pointers as to how to intelligently go about the writing and organization of this document?

Appreciate any input!
Who is Participating?
mark2150Connect With a Mentor Commented:
As for the table, yes, you should spec the format of the field *AND* the table it belongs with. Additionally you should specify if that field is indexed, must be unique, allowed to be null, etc. You should also spec the validation rules: Can't be empty, must be 15 chars, no lowercase, etc.

Yes, write it by exception. "Screen to appear as per sample, except..."

Oh for the "should not" you should have things like "Should not generate a runtime error to any incorrect operator input.", "Should not overwrite existing data without confirmation", "Should not crash if print jobs are aborted". "Shall not accept incorrectly formatted data", etc.

Input and output DATA files. The .DLL's and such are structural program files. But if your software generates data files or requires data files for it's operation, these need to be completely defined. If your software is going to use an .INI file, then the software should be able to create the file *cold*. Ideally the .EXE is the only thing that you need. It should "grow" any support/configuration files. Many times I've seen programs that require a .CFG file that cant *create* the damn thing! If it's got some obscure binary info in it (like an encrypted password) and it accidentially gets deleted then your customer is *HOSED*, they can't run the program without it and they can't recreate it! If your program is going to rely on initialization files for it's operation then it needs to be able to generate a fresh set when run in an otherwise empty directory. It's OK to have it confirm with "Configuration file not found, Create? Y/n" and then *DIE* if the answer is "No", but launching and then choking with "Configuration file not found" (or worse yet, "ERROR 53") and then stopping is unacceptable.

The .DLLs and related files are part of the deliverable and should be included in the language of the contract as such with an open ended clause like "Deliverables to include all files necessary for installation and operation of the software on a new system". This is also one of the ATP steps: "Demonstrate successful installation and operation of the software on a new system with distribution media."

The .RPT files, yes, those should be specified and documented. Essentially anything that your program needs to run should be included/documented.

You may want to set up a system *cold* and then use Ghost or somesuch to snapshot it in the naked state. After each beta, restore the machine to zero and have them reinstall.


Requirements documents have no "cast in stone" format or style.

Start off by polling your user community and ask them to give you a "blue sky" wish list of features/enhancement/fixes. Have them rate the relative importance of each on. That is if they give you a list of 50 items, have them rank the items in order of importance. Do this for all of the *users* and then combine the results. This is your "ultimate" target. You're *NOT* going to fulfill *ALL* of these items in finite time/dollars.

Give the list to your program development team and have them rate the items as to complexity and estimated time to implement.

Once you have these two documents you can then go to management and get the general schedule/cost that they are willing to spend. Starting with the #1 user request total the estimated costs/time until you reach the budget/calendar limit (whichever comes first). At this point you draw a cut off line. All items below this point are slated for the "next" version. What you have left is the core of your requirements document.

For each item have someone go thru and write a prose description of how the feature is supposed to operate. The prorgamming team will then use this as the implementation plan.

Required reading prior to this effort is "The Mythical Man-Month" by Fred Brooks. He of "Brook's Law" fame: "Adding manpower to a late software project makes it later." This is *NOT* a joke, he has the figures to back it up!

Remember there are three parameters to any project, time, cost, and quality. You can only control any two. Again, this is not a joke. Management will try to set constraints on all three - this is the road to disaster. Allow management to set any two and reserve the right to adjust the third as required and your project will be a success. Stick to your guns on this or you'll *DIE*.

Assume Management wants to control:
Time & Quality = Fast & Good = High Cost
Time & Cost = Fast & Cheap = Low Quality
Cost & Quality = Cheap & Good = Takes Forever

Beware the pitfalls of the PERT/GANTT chart. There is a tendency to "work to the schedule", that is, if an item on the PERT chart is scheduled for, say, three weeks, it will tend to consume three weeks even if the effort required was only one week.

If you have broken your task up into lots of roughly equal subtasks and you've estimated honestly, a certain percentage of your estimates will be wrong. Some will be high, some will be low, all things being equal, they should be randomly distributed thruout your project schedule. If this is all true, and your staff has been working "on" schedule, then the *one* item you underestimated at the end of the project will slip the *ENTIRE* project. *BANG* YOU'RE DEAD!

The way out of this hole is to work as fast as possible (consistent with maintaining quality) to get ahead of schedule so when that one "mis-estimated" task hits you've got some slack left in the schedule to cover the slippage with.

Take your best estimates of cost/time and *DOUBLE* them. Hit management with these #'s and let them *CHOKE*. Then back down on your numbers 25-30% and say you can do it for that level. Since there are *ALWAYS* unexpected snags you *MUST* have project surplus in time/$$$ that is at a minimum of 10% (preferably 25%) of the project.

I had a project that I'd estimated out at 10 months with a fulltime crew of six. The owner of the company - without asking - told the customer we'd do it in 6 months. We had to go to double shifts and work everyone frentically. Quality started to slip but the attitude was "We've got to make quota - SHIP IT!". The customer's QA inspector was on vacation the first couple of weeks that the deliverables started to arrive. By the time the customers QA inspector got around to checking the work, we were at the 40% completion point. What he saw *appalled* him and he blew the "STOP WORK" whistle. We fired our QA inspector on the spot (in front of the customer in a meeting!) and the project eventually took over a year to complete. We essentially had to scrap and completely re-do the 40%. The customer's QA inspector was *VERY* hard on us and was rejecting work that he would have passed had we not suffered the quality problem initially. We actually lost money on the job. You sure can't make *that* up on "volume".

Hope this helps. I've been an aero-space engineer for 20 years and these were some hard lessons to learn...


ThorinAuthor Commented:

THANK YOU very much.  You have some fantastic information in there.  I am only rejecting your answer because I want to keep the question open a little longer for more input.


One of the things I failed to mention (and I would love more of your input mark2150)is that although my team is in charge of design for this software, the costs and time frames are being set by the development team.  The reason for this is that we have chosen to hire the programming work out to a contractor, and they have set what they think the costs and timeframes will be based on what current version looks like, and what the major changes will be.  Most of the revisions or changes for the new version have been predetermined (using the suggestion of polling current users) and so the contractor was able to determine the time frames and costs.
The hiring of contract development presents good and bad aspects.  On the good side it leaves time and cost up to the contractor.  He has set a price and timeframe (given us a written bid), and if it takes longer or costs him more, he loses money.  Much as a bid for a construction project would affect a construction contractor.  On the bad side, it makes it imperative that we (my team) develop a detailed requirements document that leaves no question of what and how the software should work.  The plan at this point is to go through every screen, field, and function of the current version and write out the changes that we want to have made.  Is this the best way to do it?  Or should we start from scratch?
What I really need to know is if there are certain 'conventions' that are more useful or more understandable to use while writing this document.  Do we need to have drawings of screens and if so, are there programs available to help with that?  Things along this line...
Protect Your Employees from Wi-Fi Threats

As Wi-Fi growth and popularity continues to climb, not everyone understands the risks that come with connecting to public Wi-Fi or even offering Wi-Fi to employees, visitors and guests. Download the resource kit to make sure your safe wherever business takes you!

You should snapshot all of the screens and capture them into your specifications document. The tighter that you can make the spec the better for all concerned.

You need to have razor sharp milestones and specific performance criteria.

If your program is PC based you can do wonders with Microsoft Word. Run the program, Press <Alt PrtSc> to capture. Use <Alt Tab> to pop back to your Word document, drop the cursor where you want it and press <Ctrl V> to paste the picture in. You can then write the prose description of the changes with an *exact* image of the specific screen.

Make mock ups of the printouts.

Insist on structural specifications of all files - input *AND* output. Fields, sizes, types, etc.

Make *SURE* that you get the contractor to sign an agreement that *YOUR COMPANY* gets the rights to the SOURCE. The project should be done as a "Work for Hire". When the project is done, your company owns *all* of the rights - and the source code.

Insist on proper documentation. Specify that routines have a header with a list of all global variables referenced and those changed. Additionally their documentation should have appropriate formatting and layout guidelines (ie. preceed all labels with a comment line, follow all conditional branch statements with a comment line, indent all loops, etc., etc., etc.)

Many people do not realize that the legal definition of the word "software" *INCLUDES* documentation. Do not let them say, "heres the .exe - see ya!". They should be required to supply a users manual, supervisors reference (install/setup) and other related documentation. If it's a windows program you need to spec that they supply the online help files. The manuals & docs should be delivered in three formats: Hard copy, original format (ie. Word) and online readable (typically Adobe PDF).

When you write your specs make sure that you also include the negative. Don't just write "the program must...", you also need to specify what the program will NOT do.

Accept no "runtime" errors. Specify that the program be immune to all forms of invalid inputs. A notorious error is feeding a comma into an input statement will *hose* sloppily coded software. The Navy just had an entire *ship* go dead for three hours because someone entered an oh "O" where the program required a zero "0"! (or maybe it was the other way 'round - in either case the input should have been validated to tolerate that kind of operator error.)

One test of a program is what happens if the user simply presses <Enter> to all prompts - does the software produce *something* useful? If so, then the greenest user will be able to learn it.

Specify test cases. The test cases should include:

Clearly acceptable
Marginally acceptable
Marginally rejectable
Clearly rejectable

The software needs to include setup and configuration disks and materials suitable for a "cold" install on a just purchased machine.

Insist that an uninstaller also be supplied.

Write an ATP (Acceptance Test Procedure). Hold them to it.

Programmer productivity has been 1 fully debugged & documented line of code per *man-hour* for years.

Remember - you get what you pay for!


ThorinAuthor Commented:
Oh yeah, get what you pay for is absolutely true!  That is why we finally bought this product from its previous developer, and went our own way.  Great concept and market, shoddy programming.

I have a couple of questions for you:

Define more what you were saying about "Insist on structural specifications of all files - input *AND* output. Fields, sizes, types, etc"  Do you mean we should define pixel size (height and width) for every field and screen etc.  And what do you mean by input and output?  

Tell me more about 'test cases', are you referring to real-life examples, or putting the software through programmer tests, or both, neither?

Define the ATP for me, and what from a macro point of view that would look like.

Now you're on it...this is just what we are looking for! :)
Was referring to DATA files, not screens. If they create a binary data file you've got to know what's in it. Input files are files that are READ by your program, output files are files that are CREATED by your program (I'm having to speak in general terms as I have no clue as to what your app is, this general stuff applies to ANY project...)

Both. Beware of them building a "test case passer". This is a software module that correctly runs the test cases but fails miserably on "real world" data.

An ATP becomes part of the contractural specification for the product. It lists a series of specific behaviour characteristics that the software must exhibit before you *PAY* the bill!
Typically a milestone is reached when the software passes the ATP. This is the "Final Exam" for the software. When YOU sign off on the ATP you're accepting that the software works as advertised. The "procedure" is generally a hard performance metric. ie. "The software will correctly print the xyz report using the actual data for July 1998.", "The program will accept all pre-existing data from the supplied data files.", etc., etc., etc.

When the program passes the ATP you're both assured that the program works. They get the check, and you get a functioning program. An ATP needs to be detailed, specific and comprehensive. It's tough to write a good one, but having one eliminates lawsuits.

Think of it like a contractors "punch list" when you buy a house. They do a "walk thru" and check that all the windows open, the doors don't squeek, the toilets flush, etc. Normally you don't pass on the first try (if they do, you didn't write a tight enough ATP!). There is typically a list of "deficiencies" that they will then address until the ATP passes in all respects. You're holding on to the final check until the ATP passes so their well motivated. The ATP can also include such items as "Users manual delivered and verified for proper operation of the program." This is too loose, but you get the drift.

ThorinAuthor Commented:
Ok...thanks for answering those questions.  I agree with you that an ATP is a sound idea.  But I think it just extended our time for writing this documentation!  Thanks a lot. :)  Fortunately for us, we have created more of a long term agreement with this contract programmer, and part of their payment is royalty based, and their royalties based on copies of the product that THEIR company sells.  They are basically going to work as a dealer for us, once the product is completed.  I am not sure why you need to know that...but it helps alleviate some concerns of the developer just walking away.

Back to the actual requirements document, I am not sure if there is any more I can get out of you, but you have proven to be a fount of information.  But I still have a couple of questions:

When we are working on defining the screens should we define the database structure specifically, or can we state something like: "In this section of the screen there should be a text input field, that contains a max of 50 characters.  This field should be labeled Company Name."  Is that enough, or do we need to put information about what table and what ??? of the database the information needs to go into?

Is it enough to say "This screen of the program will look exactly the same as previous version, except..." or do we need to define each and every section of the program?

Earlier you stated that we need to define what the program will not do.  That is pretty broad.  How do you mean that?  

Lastly, I am still a little fuzzy by what you mean with regards to input and output.  This kind of goes back to my first question, but, how specific do I need to be?  Do I need to define all the .DLL calls the program makes, and what .RPT files it needs to run a report, etc etc.?

Really appreciate all your help on this...lets call this the last round.  If you can give me your response in answer, I will give you your points.  Thanks!
ThorinAuthor Commented:

Thanks for all your help.  I think it will help us to create a better software program.

Hey no problem. Let me know how it turns out!

I've managed some fair sized projects and worked on several *LARGE* puppies over the years. Be sure to pick up a copy of "The Mythical Man Month". The guy that wrote it was responsible for the development of the IBM 360 OS. He went $300,000,000 *OVER* budget and was *TWO YEARS* late. If he'd worked for any company smaller than IBM they'd have *died* from that ONE ERROR! When he looks back, y'all need to listen - typical quote: "How does a project get to be a year late? ... One day at a time." Best book on software management I've ever read & i've been in the biz since punched cards.

Keep in touch at


ThorinAuthor Commented:
Will do...and if any more questions come up......
I'll let you know when it is done and you can see a little of what we were talking about.  

Thanks again.

Question has a verified solution.

Are you are experiencing a similar issue? Get a personalized answer when you ask a related question.

Have a better answer? Share it in a comment.

All Courses

From novice to tech pro — start learning today.