| -Prev | -Chapter 6. Engineering Standards | -Next - | -
|---|
-
- Briefly explain to the reader what this document is for, whether
+
+ 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,
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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.
+ 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-