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.
+Very broadly, describe how the system +meets a need of a business, group, the OpenACS 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.
+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.
You should also state the context and +dependencies of the system here, e.g. if it's an application-level +package for OpenACS 4, briefly describe how it uses kernel +services, like permissions or subsites.
+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.
+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.
+Include all pertinent links to supporting and related material, +such as:
System/Package "coversheet" - where all documentation for this +software is linked off of
Design document
Developer's guide
User's guide
Other-cool-system-related-to-this-one document
Test plan
Competitive system(s)
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.
10.0 A Common +Solution
Programmers and designers should only have to learn a single +system that serves as a UI substrate for all the functionally +specific modules in the toolkit.
+10.0.1
The system should not make any assumptions about how pages +should look or function.
10.0.5
Publishers should be able to change the default presentation of +any module using a single methodology with minimal exposure to +code.
+
For guidelines writing requirements, take a look at the quality standards, along with a good +example, such as Package Manager +Requirements.
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.
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.
+| Document Revision # | Action Taken, Notes | When? | By Whom? | +
|---|---|---|---|
| 0.3 | Edited further, incorporated feedback from Michael Yoon | 9/05/2000 | Kai Wu | +
| 0.2 | Edited | 8/22/2000 | Kai Wu | +
| 0.1 | Created | 8/21/2000 | Josh Finkler, Audrey McLoghlin | +