System/Application Requirements Template

by Joe Programmer, Jane Coder

I. Introduction

Briefly explain to the reader what this document is for, whether it records the requirements for a new system, a client application, a toolkit subsystem, etc. Remember your audience: fellow programmers, AND interested non-technical parties such as potential clients, who may all want to see how rigorous our engineering process is. Here and everywhere, write clearly and precisely; for requirements documentation, write at a level that any intelligent layperson can understand.

II. Vision Statement

Very broadly, describe how the system meets a need of a business, group, the ACS as a whole, etc. Make sure that technical and non-technical readers alike would understand what the system would do and why it's useful. Whenever applicable, you should explicitly state what the business value of the system is.

III. System/Application Overview

Discuss the high-level breakdown of the components that make up the system. You can go by functional areas, by the main transactions the system allows, etc.

IV. Use-cases and User-scenarios

Determine the types or classes of users who would use the system, and what their experience would be like at a high-level. Sketch what their experience would be like and what actions they would take, and how the system would support them.

(Optional: Competitive Analysis)

Describe other systems or services that are comparable to what you're building. If applicable, say why your implementation will be superior, where it will match the competition, and where/why it will lack existing best-of-breed capabilities. This section is also in the Design doc, so write about it where you deem most appropriate.

V. Related Links

Include all pertinent links to supporting and related material, such as:

Design document
System Overview document
Other-cool-system-that-relates-to-this-one document
Test plan for this system
Competitive system

VI.A (B, C, D, etc.) Requirements

The main course of the document, requirements. Break up the requirements sections (A, B, C, etc.) as needed. Within each section, create a list denominated with unique identifiers that reflect any functional hierarchy present, e.g. 20.5.13. - for the first number, leave generous gaps on the first writing of requirements (e.g. 1, 10, 20, 30, 40, etc.) because you'll want to leave room for any missing key requirements that may arise.

For guidelines writing requirements, take a look at the quality standards, along with a good example, such as the requirements for APM v4.

Besides writing requirements in natural language, consider using the following techniques as needed:

Pseudocode - a quasi programming language, combining the informality of natural language with the strict syntax and control structures of a programming language.

Finite State Machines - a hypothetical machine that can be in only one of a given number of states at any specific time. Useful to model situations that are rigidly deterministic, that is, any set of inputs mathematically determines the system outputs.

Decision Trees and Decision Tables - similar to FSMs, but better suited to handle combinations of inputs.

Flowcharts - easy to draw and understand, suited for event and decision driven systems. UML is the industry standard here.

Entity-Relationship diagrams - a necessary part of Design documents, sometimes a high-level ER diagram is useful for requirements as well.

(Optional: Implementation Notes)

Although in theory coding comes after design, which comes after requirements, we do not, and perhaps should not, always follow such a rigid process (a.k.a. the waterfall lifecyle). Often, there is a pre-existing system or prototype first, and thus you may want to write some thoughts on implementation, for aiding and guiding yourself or other programmers.

VII. Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	00/00/2000	Jane Coder

kai@arsdigita.com

Last modified: $Date: 2001/01/19 21:36:44 $