Index: openacs-4/packages/acs-core-docs/www/requirements-template.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v diff -u -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/requirements-template.html 7 Mar 2002 06:55:36 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/requirements-template.html 10 Aug 2002 20:07:21 -0000 1.8 @@ -1,242 +1,86 @@ - - - -System/Application Requirements Template - - - - - - - - - -
-

-System/Application Requirements Template

-

By You -

-
-

-Introduction

-

- Briefly explain to the reader what this document is for, whether +System/Application Requirements Template

System/Application Requirements Template

By You


+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

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. -

-
-
-

-Vision Statement

-

+ understand. +

Vision Statement

- Very broadly, describe how the system meets a need of a business, + 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. -

-
-
-

-System/Application Overview

-

- Discuss the high-level breakdown of the components that make up + what the business value of the system is. +

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. -

-

- You should also state the context and dependencies of the system + 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. -

-
-
-

-Use-cases and User-scenarios

-

- Determine the types or classes of users who would use the + describe how it uses kernel services, like permissions or subsites. +

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 + 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. -

-
-
-

-Related Links

-

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)

  • -
-
-
-

-Requirements

-

- The main course of the document, requirements. Break up the + Design doc, so write about it where you deem most appropriate. +

Related Links

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)

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. -

-
  • -

    10.0 A Common Solution

    -

    + 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

      -

      +

      10.0.1

      The system should not make any assumptions about how pages should look or function. -

      -

      10.0.5

      -

      +

      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 OpenACS 4.5 Package Manager Requirements. -

-

+

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

-
    -
  • Pseudocode - a quasi programming language, combining the +

    • 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 + 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 + 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 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. -

-
-
-

-Revision History

-
------ - - - - - - - - - - - - - - - - - - - - - - - - - - -
Document Revision #Action Taken, NotesWhen?By Whom?
0.3Edited further, incorporated feedback from Michael Yoon9/05/2000Kai Wu
0.2Edited8/22/2000Kai Wu
0.1Created8/21/2000Josh Finkler, Audrey McLoghlin
-

($Id$)

-
-
-

Revision History

Document Revision #Action Taken, NotesWhen?By Whom?
0.3Edited further, incorporated feedback from Michael Yoon9/05/2000Kai Wu
0.2Edited8/22/2000Kai Wu
0.1Created8/21/2000Josh Finkler, Audrey McLoghlin

($Id$)
- - +