D4P: Requirements Document Guidelines

CS486 - Senior Capstone Design

Requirements, Functions and Project Plan Document Guidelines

Executive Summary: What are we working to produce here?

A concise 6-15 page document detailing customer needs, functional requirements, and your plan for accomplishing the project. This document forms the legal basis for your execution of the project. Once the client signs off on this document, both sides know and are bound by what is expected as a deliverable.

Requirements, Functions and Execution Plan Document

Customer Concept Requirements Functional Spec Detailed Design Code

In the modern Agile design environment, the traditional "project preparation and analysis" project is truncated, with the goal of moving as quickly as possible to the prototype stage. Some of the things that fall away are detailed market and risk analyses, lengthy project proposals, and iterative sets of requirements and functional specs.

What remains vital, however, is that the team have a detailed understanding of the requirements/goals of the client and how these translate into specific product functions before any programming is done. Thus, the primary purposes of a requirements, functions, and execution plan document are:

To display an understanding of the client's business overall, what specifically is missing/weak currently, and a vision of how the proposed software will meet those needs. This ensures that you and the client are on the same page to start with!
To then list out the requirements the client has of the software, expressed in terms drawn from the domain. For example, domain-level requirements for a retail ERP system might include "must allow entry of new customers" and "must support statistical analysis of sales over time including daily, monthly, and yearly gross, averages, and incomes". Note there is no geek language about how the system will provide these functions!
These requirements are then translated into specific functions in the program/interface. In contrast to the requirements in (2), you should feel free to use technical language here. Describe carefully what functions the software will need to be able to do in order to satisfy each of the requirements; there are typically many function specifications for each of the higher level performance specs.
The last section of the document is a description of your execution plan. Give an overview of how you see breaking the work up by defining a number of meaningful "milestones" or "phases" in the project. These are usually major accomplishments --- points at which progress can be clearly defined and evaluated. Then place these milestones on a timeline. Note that work on several milestones will often overlap, i.e., your team can be working on several components/sub-projects in parallel, which are then brought together at some later point.

In sum, this document is the first deliverable from the design team to the customer. It provides the customer with a clear picture of what the design team believes the customer wants, how those high-level requirements map to specific software functionality, and how the team sees fitting the project into the required timeframe. If accepted by the customer, this document contractually establishes the scope and content of the project --- it is what you and the customer refer to in determining (perhaps in a court of law!) to what extent the project was performed in a competent and timely manner. It is important to ensure that it is complete, consistent and correct.

RFP Document: Suggested Content Outline

As a starting point, the requirements document must include:

1. Cover page

Project title
Names of team members
Date of last revision
Revision number in the form "rev x.x" --- x.x denotes the revision number. 1.0 is usually the first revision. Major revisions cause increments in the digit to the left of the decimal while minor revisions cause increments in the digit to the right.

2. Table of Contents

3. Introduction -- Executive summary that briefly (1-2 paragraphs) describes the problem, objective of the project, and high level requirements statements.

4. Problem Statement -- Demonstrate a deep understanding of the clients problem and desired solution. Having a "deep" understanding means not simply proposing a software product out of the blue (i.e., here's what the client says he wants), but showing that you understand the underlying problem/task that the client is needing to address with this software, have analyzed this "big picture" problem and have considered multiple possible solutions (not just the one the client may have hit upon first) to solve the problem. This section is extremely important, as you will re-use it again and again in later documents and presentations to introduce your project. Your goal here is to "sell" your project to the audience. Don't just say "here's this company, this is what they sell, and they told us to do this project", you want to tell a coherent story about the company, their problem, past ways of tackling it --- and then leave us saying to ourselves "yeah, this is a tough problem, gee, I wonder how these guys are going to solve it". If you fail to convey this information in a clear and compelling fashion, your whole project will appear pointless! Here are some topics you might touch on as you weave together the intro:

Background/history -- what does the company do overall, how did the problem arise, what is the larger context, how did users get the job done in the past.
Business issues -- Why is the problem task(s) to be addressed important to the business. Why should they spend any time/money solving this thing? Some things that might be relevant to the business, depending on your project, are accuracy (of data processing, whatever), speed, timeliness, data accessibility. Say a few general words alluding to cost/benefit as well (with more later).
Competitive products/research -- Talk about other products that could conceivably be applied to solve this problem. You don't want to re-invent the wheel if an off-the-shelf solution exists; convince the client that you've considered this and that this is not the case.
Summarize the preceding discussion with a bulleted list of what the challenges are that a software solution would need to solve to address this problem. This sets you up for the next section where (tada!) you present a visionary solution that addresses exactly these needs.

5. Product/solution Statement -- Here is where you present your vision of system that will solve this problem. Vision here means a high-level conceptual description of how the system will work to solve the problem, and NOT (many of us geeks fail here!) some technical description or UML diagram of how you plan to solve it. Talk about overall processing steps and conceptual components, not software components. A non-geek with reasonable technical background (e.g., the vice president of a tech. company) should be able to understand and be convinced you have a brilliant solution. Some specific goals here might include:

Start with a conceptual description of your solution. If you dive into technical detail right away, you'll lose the audience. You've just (previous section) spent careful effort convincing folks there's a real problem to be solved. That's your pitch, now hit it out of the park! You should be able to sketch out your solution concept with one diagram and around a page of text -- any more and you'll lose you momentum. Close your solution sketch with a set of bulleted features of your solution; these features should closely parallel (and solve!) the bullets you presented in the last section where you described what needs a solution would have to address. Do a little sales job here: gloss over details, focus on the positive, make this sound like the greatest idea since sliced bread.
After your conceptual overview, the readers should have a solid overall idea of what you're doing and be convinced that it's great. Now go back and fill in just a few details --- just enough to convince the geeks that might be reading that you know what you're doing and have a solid architectural vision. Give a brief sketch of your technical approach, plus a coarse architecture diagram and briefly walk through how the various components work together to perform the overall system function.

6. Requirements and Functional Spec -- Here's THE MEAT of the document! In this section, you are going to follow up on your preceding vision with a listing of specific requirements and corresponding functionality. Above, you laid out what it would do in broad strokes, here you give a laundry list of specific capabilities. I recommend organizing this hierarchically: You have top-level list items that are the customer REQUIREMENTS as section headings. Subsections describe the requirement is detail (see below), and then have a SPECIFIC FUNCTIONAL SPECS section that enumerates the specific system functionalities that will support this requirement.

Customer REQUIREMENTS. The point here is essentially to echo back the behaviors and vision that the client has in mind for the product. This gives the client a chance to correct misunderstandings, or to further clarify or extend the description to include things that were missed. You will generally have a substantial list of customer requirements covering various desired behaviors of the product. For each one, there are two parts: functional requirements and performance requirements.

Functional Requirements - The functional part of a customer requirement gives a detailed description of what the software should be able to do. It is critical to be detailed here --- if you just put down a few sentences, there is a good chance that you will be thinking one thing, while the customer is thinking another. There are a number of things you can do here. FIRST, give a clear concise verbal description of the functionality the customer wants. This could be a short 2-3 sentence description of the behavior as a whole, plus some bullets to define various details. THEN, to make sure you have understood clearly, give one or more Use Cases that illustrate how the functionality in question is accessed by the end-user to do some real task from the domain. Here are some Use Case guidelines that give some hints on how to present Use Cases effectively.

Performance Requirements. A short section where you say specifically how fast/well/error-free the product you produce will be able to perform the required function you've just described. For example, if the requirement is something like "Must be able to enter new customers and their profiles", then a performance requirement might be "90% of users will be able to enter a new customers and profile in 23 seconds, after two training rounds". Or maybe "90% of users will be able to access (for editing) any field in a customer profile in less than 5 seconds, after 5 training rounds". Or maybe "after 5 training rounds, 95% of users will be able to create a new customer profile after two weeks" (testing memorability of interface). There are two critical points here: First, you must present specific measurable metrics here! Things like "the interface will be user-friendly" are useless fluff! Second, you will be expected to actually perform these measures and live up to them in the final pre-delivery acceptance testing of your product! This is what you are guaranteeing your client, and you will be asked to live up to it --- or not get paid!

Functional SPECIFICATION. I usually put these in subsections under each requirement, to better show which functionalities support which overall requirements. The only problem with this is, of course, that some functional characteristics might support not just one, but several overall requirements. In this case, you just list them again under the section(s) for the other requirement(s) they support. Functional Specifications are detailed descriptions of specific functionalities that the system must achieve in order to support a particular requirement. Think about it this way: an implementor/designer should be able to read the functional specs and know exactly what to create. So the overall requirement of "Support entry of new customer profiles", you might have a number of functional specs like: "Must have controls to initiate creation of new customer"; "Must allow editing of existing customer profiles", "must allow searching and sorting of customers profiles", and so on. Most functional specs will be no more than 2-3 lines long ---- though some might be longer if they require more explanation. Remember: enough detail for an implementor to design a solution without coming back to ask you for details, BUT try to stay away from specific implementations (that's up to the designer in the next step). So note that in the examples above I didn't say "have a button to initiate creation of new user" --- all I said was "controls"; it's up to the designer/implementer to make the final "how" decision...

7. Constraints and Feasibility Issues -- Under Constraints, you discuss any hardware/software constraints, environmental issues (e.g. what type of environment it has to work in), compatability constraints, or cost constraints. These are all things the customers may have communicated to you as "ground rules" for your implementation. Under Feasibility Issues, you will want to mention any concerns or possible constraints involving economics, technical feasibility, resources, or legality that you can foresee in the design. Don't need to elaborate to much, just list them. For instance, if you are assuming that you will have certain equipment/software available, that certain technical issues will be surmountable, or you're not sure something is legal, list it here. If you have nothing applicable, leave the section away...

8. Project Execution Plan --- Give a brief sketch (1 page or so) that succintly lays out your plan for tackling this project and getting it done by the deadline (Capstone day). Lay out your project as 5-10 milestones, which should represent the major phases of the project. Describe each milestone briefly in itemized text discussing your work to meet that milestone, then graphically display these milestones on a calendar timeline. If you are creating an end-user (vs. embedded) application, make sure you build in time for user-testing and refinement at the end! Finally, you'll want to discuss briefly where you suspect you may have slippage in the schedule, and how you'll accommodate, i.e., which other phases you can see compressing to make up time if needed.

9. Appendices -- To contain any supplementary material needed to communicate the project requirements. For instance, specs on some software product you'll use, government regulations that apply, etc.