Table of Contents
By You
-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. -
+ + +
+ ++ 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 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. -
-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 ACS 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:
-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 ACS 4 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. -
+ 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 OpenACS 4 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. +
+