Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml 13 Mar 2001 22:59:26 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml 30 Dec 2001 01:29:07 -0000 1.2
@@ -1,412 +1,409 @@
-Detailed Design Documentation Template
+ Detailed Design Documentation Template
-
-
-By You
-
+ By You
+
+
+ Start Note
+
+ NOTE: Some of the sections of this template may not apply to your
+ package, e.g. there may be no user-visible UI elements for a component
+ of the OpenACS Core. Furthermore, it may be easier in some circumstances
+ to join certain sections together, e.g. it may make sense to discuss
+ the data model and transactions API together instead of putting them
+ in separate sections. And on occasion, you may find it easier to
+ structure the design discussion by the structure used in the
+ requirements document. As this template is just a starting point, use
+ your own judgment, consult with peers when possible, and adapt
+ intelligently.
+
-
-Start Note
-
-NOTE: Some of the sections of this template may not apply to your
-package, e.g. there may be no user-visible UI elements for a component
-of the ACS Core. Furthermore, it may be easier in some circumstances
-to join certain sections together, e.g. it may make sense to discuss
-the data model and transactions API together instead of putting them
-in separate sections. And on occasion, you may find it easier to
-structure the design discussion by the structure used in the
-requirements document. As this template is just a starting point, use
-your own judgment, consult with peers when possible, and adapt
-intelligently.
-
+
+ Also, bear in mind the audience for detailed design: fellow
+ programmers who want to maintain/extend the software, AND parties
+ interested in evaluating software quality.
+
-
-Also, bear in mind the audience for detailed design: fellow
-programmers who want to maintain/extend the software, AND parties
-interested in evaluating software quality.
-
+
-
+
+ Essentials
-
-Essentials
+
+ When applicable, each of the following items should receive its own link:
+
-
-When applicable, each of the following items should receive its own link:
-
+
+ User directory
+ OpenACS administrator directory
+ Subsite administrator directory
+
+ Tcl script directory (link to the API browser page for the package)
+ PL/SQL file (link to the API browser page for the package)
+ Data model
+
+ Requirements document
+ ER diagram
+ Transaction flow diagram
+
-
- User directory
- ACS administrator directory
- Subsite administrator directory
-
- Tcl script directory (link to the API browser page for the package)
- PL/SQL file (link to the API browser page for the package)
- Data model
-
- Requirements document
- ER diagram
- Transaction flow diagram
-
+
-
+
+ Introduction
-
-Introduction
+
+ This section should provide an overview of the package
+ and address at least the following issues:
+
-
-This section should provide an overview of the package
-and address at least the following issues:
-
+
+ What this package is intended to allow the user (or different
+ classes of users) to accomplish.
-
- What this package is intended to allow the user (or different
-classes of users) to accomplish.
+ Within reasonable bounds, what this package is not intended to allow users to
+ accomplish.
- Within reasonable bounds, what this package is not intended to allow users to
-accomplish.
+ The application domains where this package is most likely to be of use.
- The application domains where this package is most likely to be of use.
+ A high-level overview of how the package meets its
+ requirements (which should have been documented elsewhere). This
+ is to include relevant material from the "features" section of the
+ cover sheet (the cover sheet is a wrapper doc with links to all
+ other package docs).
+
- A high-level overview of how the package meets its
- requirements (which should have been documented elsewhere). This
- is to include relevant material from the "features" section of the
- cover sheet (the cover sheet is a wrapper doc with links to all
- other package docs).
-
+
+ Also worthy of treatment in this section:
+
-
-Also worthy of treatment in this section:
-
+
+ When applicable, a careful demarcation between the
+ functionality of this package and others which - at least
+ superficially - appear to address the same requirements.
+
-
- When applicable, a careful demarcation between the
- functionality of this package and others which - at least
- superficially - appear to address the same requirements.
-
+
+ Note: it's entirely possible that a discussion of what a package
+ is not intended to do differs from a discussion of future
+ improvements for the package.
+
-
-Note: it's entirely possible that a discussion of what a package
-is not intended to do differs from a discussion of future
-improvements for the package.
-
+
-
+
+ Historical Considerations
+
-
-Historical Considerations
-
+
+ For a given set of requirements, typically many possible
+ implementations and solutions exist. Although eventually only one
+ solution is implemented, a discussion of the alternative solutions
+ canvassed - noting why they were rejected - proves helpful to both
+ current and future developers. All readers would be reminded as to
+ why and how the particular solution developed over time, avoiding
+ re-analysis of problems already solved.
+
-
-For a given set of requirements, typically many possible
-implementations and solutions exist. Although eventually only one
-solution is implemented, a discussion of the alternative solutions
-canvassed - noting why they were rejected - proves helpful to both
-current and future developers. All readers would be reminded as to
-why and how the particular solution developed over time, avoiding
-re-analysis of problems already solved.
-
+
-
+
+ Competitive Analysis
-
-Competitive Analysis
+
+ Although currently only a few package documentation pages contain a
+ discussion of competing software, (e.g. chat, portals), this section
+ should be present whenever such competition exists.
+
-
-Although currently only a few package documentation pages contain a
-discussion of competing software, (e.g. chat, portals), this section
-should be present whenever such competition exists.
-
+
+ If your package exhibits features missing from competing
+ software, this fact should be underscored.
-
- If your package exhibits features missing from competing
-software, this fact should be underscored.
+ If your package lacks features which are present in competing
+ software, the reasons for this should be discussed here; our sales
+ team needs to be ready for inquiries regarding features our software
+ lacks.
+
- If your package lacks features which are present in competing
-software, the reasons for this should be discussed here; our sales
-team needs to be ready for inquiries regarding features our software
-lacks.
-
+
+ Note that such a discussion may differ from a discussion of a
+ package's potential future improvements.
+
-
-Note that such a discussion may differ from a discussion of a
-package's potential future improvements.
-
+
-
+
+ Design Tradeoffs
+
-
-Design Tradeoffs
-
+
+ No single design solution can optimize every desirable software
+ attribute. For example, an increase in the security of a system will
+ likely entail a decrease in its ease-of-use, and an increase in the
+ flexibility/generality of a system typically entails a decrease in the
+ simplicity and efficiency of that system. Thus a developer must decide
+ to put a higher value on some attributes over others: this section
+ should include a discussion of the tradeoffs involved with the design
+ chosen, and the reasons for your choices. Some areas of importance to
+ keep in mind are:
+
-
-No single design solution can optimize every desirable software
-attribute. For example, an increase in the security of a system will
-likely entail a decrease in its ease-of-use, and an increase in the
-flexibility/generality of a system typically entails a decrease in the
-simplicity and efficiency of that system. Thus a developer must decide
-to put a higher value on some attributes over others: this section
-should include a discussion of the tradeoffs involved with the design
-chosen, and the reasons for your choices. Some areas of importance to
-keep in mind are:
-
+ Areas of interest to users:
-Areas of interest to users:
+
+ Performance: availability and efficiency
+ Flexibility
+ Interoperability
+ Reliability and robustness
+ Usability
+
-
- Performance: availability and efficiency
- Flexibility
- Interoperability
- Reliability and robustness
- Usability
-
+ Areas of interest to developers:
-Areas of interest to developers:
+
+ Maintainability
+ Portability
+ Reusability
+ Testability
+
-
- Maintainability
- Portability
- Reusability
- Testability
-
+
-
+
+ API
+
-
-API
-
+
+ Here's where you discuss the abstractions used by your package, such
+ as the procedures encapsulating the legal transactions on the data
+ model. Explain the organization of procedures and their
+ particulars (detail above and beyond what is documented in the
+ code), including:
+
-
-Here's where you discuss the abstractions used by your package, such
-as the procedures encapsulating the legal transactions on the data
-model. Explain the organization of procedures and their
-particulars (detail above and beyond what is documented in the
-code), including:
-
+
+ Problem-domain components: key algorithms, e.g. a specialized
+ statistics package would implement specific mathematical procedures.
-
- Problem-domain components: key algorithms, e.g. a specialized
- statistics package would implement specific mathematical procedures.
+ User-interface components: e.g. HTML widgets that the package may need.
- User-interface components: e.g. HTML widgets that the package may need.
+ Data management components: procedures that provide a stable
+ interface to database objects and legal transactions - the latter
+ often correspond to tasks.
+
+
- Data management components: procedures that provide a stable
- interface to database objects and legal transactions - the latter
- often correspond to tasks.
-
-
+
+ Remember that the correctness, completeness, and stability of the API
+ and interface are what experienced members of our audience are looking
+ for. This is a cultural shift for us at aD (as of mid-year 2000), in
+ that we've previously always looked at the data models as key, and
+ seldom spent much effort on the API (e.g. putting raw SQL in pages to
+ handle transactions, instead of encapsulating them via procedures).
+ Experience has taught us that we need to focus on the API for
+ maintainability of our systems in the face of constant change.
+
-
-Remember that the correctness, completeness, and stability of the API
-and interface are what experienced members of our audience are looking
-for. This is a cultural shift for us at aD (as of mid-year 2000), in
-that we've previously always looked at the data models as key, and
-seldom spent much effort on the API (e.g. putting raw SQL in pages to
-handle transactions, instead of encapsulating them via procedures).
-Experience has taught us that we need to focus on the API for
-maintainability of our systems in the face of constant change.
-
+
+ Also noteworthy is that although the OpenACS currently utilizes the
+ AOLserver Tcl API, the current drive towards Java is likely to effect
+ a change in the content of these sections in the future.
+
-
-Also noteworthy is that although the ACS currently utilizes the
-AOLserver Tcl API, the current drive towards Java is likely to effect
-a change in the content of these sections in the future.
-
+
-
+
+ Data Model Discussion
-
-Data Model Discussion
+
+ The data model discussion should do more than merely display the SQL
+ code, since this information is already be available via a link in the
+ "essentials" section above. Instead, there should be a high-level
+ discussion of how your data model meets your solution requirements:
+ why the database entities were defined as they are, and what
+ transactions you expect to occur. (There may be some overlap with the
+ API section.) Here are some starting points:
+
-
-The data model discussion should do more than merely display the SQL
-code, since this information is already be available via a link in the
-"essentials" section above. Instead, there should be a high-level
-discussion of how your data model meets your solution requirements:
-why the database entities were defined as they are, and what
-transactions you expect to occur. (There may be some overlap with the
-API section.) Here are some starting points:
-
+
+ The data model discussion should address the intended usage
+ of each entity (table, trigger, view, procedure, etc.) when this
+ information is not obvious from an inspection of the data model
+ itself.
-
- The data model discussion should address the intended usage
-of each entity (table, trigger, view, procedure, etc.) when this
-information is not obvious from an inspection of the data model
-itself.
+ If a core service or other subsystem is being used (e.g., the
+ new parties and groups, permissions, etc.) this should also be
+ mentioned.
- If a core service or other subsystem is being used (e.g., the
-new parties and groups, permissions, etc.) this should also be
-mentioned.
+ Any default permissions should be identified herein.
- Any default permissions should be identified herein.
+ Discuss any data model extensions which tie into other
+ packages.
- Discuss any data model extensions which tie into other
- packages.
+ Transactions
- Transactions
+ Discuss modifications which the database may undergo from
+ your package. Consider grouping legal transactions according to
+ the invoking user class, i.e. transactions by an OpenACS-admin, by
+ subsite-admin, by a user, by a developer, etc.
- Discuss modifications which the database may undergo from
- your package. Consider grouping legal transactions according to
- the invoking user class, i.e. transactions by an ACS-admin, by
- subsite-admin, by a user, by a developer, etc.
+
-
+
-
+
+ User Interface
-
-User Interface
+
+ In this section, discuss user interface issues and pages to be built;
+ you can organize by the expected classes of users. These may include:
+
-
-In this section, discuss user interface issues and pages to be built;
-you can organize by the expected classes of users. These may include:
-
+
+ Developers
+ OpenACS administrators (previously known as site-wide administrators)
+ Subsite administrators
+ End users
+
-
- Developers
- ACS administrators (previously known as site-wide administrators)
- Subsite administrators
- End users
-
+
+ You may want to include page mockups, site-maps, or other visual aids.
+ Ideally this section is informed by some prototyping you've done, to
+ establish the package's usability with the client and other interested
+ parties.
+
-
-You may want to include page mockups, site-maps, or other visual aids.
-Ideally this section is informed by some prototyping you've done, to
-establish the package's usability with the client and other interested
-parties.
-
+
+ Note: In order that developer documentation be uniform across
+ different system documents, these users should herein be designated as
+ "the developer," "the OpenACS-admin," "the sub-admin," and "the user,"
+ respectively.
+
-
-Note: In order that developer documentation be uniform across
-different system documents, these users should herein be designated as
-"the developer," "the ACS-admin," "the sub-admin," and "the user,"
-respectively.
-
+
+ Finally, note that as our templating system becomes more entrenched
+ within the OpenACS, this section's details are likely to shift from UI
+ specifics to template interface specifics.
+
-
-Finally, note that as our templating system becomes more entrenched
-within the ACS, this section's details are likely to shift from UI
-specifics to template interface specifics.
-
+
-
+
+ Configuration/Parameters
-
-Configuration/Parameters
+
+ Under OpenACS 4, parameters are set at two levels: at the global level by
+ the OpenACS-admin, and at the subsite level by a sub-admin. In this
+ section, list and discuss both levels of parameters.
+
-
-Under ACS 4, parameters are set at two levels: at the global level by
-the ACS-admin, and at the subsite level by a sub-admin. In this
-section, list and discuss both levels of parameters.
-
+
-
+
+ Future Improvements/Areas of Likely Change
-
-Future Improvements/Areas of Likely Change
+
+ If the system presently lacks useful/desirable features, note details
+ here. You could also comment on non-functional improvements to the
+ package, such as usability.
+
-
-If the system presently lacks useful/desirable features, note details
-here. You could also comment on non-functional improvements to the
-package, such as usability.
-
+
+ Note that a careful treatment of the earlier "competitive analysis"
+ section can greatly facilitate the documenting of this section.
+
-
-Note that a careful treatment of the earlier "competitive analysis"
-section can greatly facilitate the documenting of this section.
-
+
-
+
+ Authors
-
-Authors
+
+ Although a system's data model file often contains this information,
+ this isn't always the case. Furthermore, data model files often
+ undergo substantial revision, making it difficult to track down the
+ system creator. An additional complication: package documentation may
+ be authored by people not directly involved in coding. Thus to avoid
+ unnecessary confusion, include email links to the following roles as
+ they may apply:
+
-
-Although a system's data model file often contains this information,
-this isn't always the case. Furthermore, data model files often
-undergo substantial revision, making it difficult to track down the
-system creator. An additional complication: package documentation may
-be authored by people not directly involved in coding. Thus to avoid
-unnecessary confusion, include email links to the following roles as
-they may apply:
-
+
+ System creator
+ System owner
+ Documentation author
+
-
- System creator
- System owner
- Documentation author
-
+
-
+
+ Revision History
-
-Revision History
+
+ The revision history table below is for this template - modify it
+ as needed for your actual design document.
+
-
-The revision history table below is for this template - modify it
-as needed for your actual design document.
-
+
+
+
+
+
+ Document Revision #
+ Action Taken, Notes
+ When?
+ By Whom?
+
+
-
-
-
-
-
- Document Revision #
- Action Taken, Notes
- When?
- By Whom?
-
-
+
+
+ 0.3
+ Edited further, incorporated feedback from Michael Yoon
+ 9/05/2000
+ Kai Wu
+
-
-
- 0.3
- Edited further, incorporated feedback from Michael Yoon
- 9/05/2000
- Kai Wu
-
+
+ 0.2
+ Edited
+ 8/22/2000
+ Kai Wu
+
-
- 0.2
- Edited
- 8/22/2000
- Kai Wu
-
+
+ 0.1
+ Creation
+ 8/21/2000
+ Josh Finkler, Audrey McLoghlin
+
-
- 0.1
- Creation
- 8/21/2000
- Josh Finkler, Audrey McLoghlin
-
+
-
+ ($Id$)
-($Id$)
+
-
-
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 24 Dec 2001 19:31:43 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 30 Dec 2001 01:29:07 -0000 1.3
@@ -5,8 +5,7 @@
By claus@arsdigita.com, with
additions by Roberto
- Mello, Vinod Kurup, Talli Somekh and the OpenACS
- Community
+ Mello and the OpenACS Community
@@ -102,9 +101,70 @@
+
+
+ Tools
+
+
+ You are going to need the following to work with the OpenACS
+ Docbook XML documentation:
+
+
+
+
+ Docbook XML
+ DTD - The document type definition for XML. You can
+ find an RPM or DEB package or you can download a zip file from
+ the site linked from here.
+
+
+
+ XSL
+ Stylesheets (docbook-xsl) - The stylesheets to convert
+ to HTML. We have been using a stylesheet based upon
+ NWalsh's chunk.xsl.
+
+
+
+ xsltproc - The processor that
+ will take an XML document and, given a xsl stylesheet, convert
+ it to HTML. It needs libxml2 and libxslt (available in RPM and
+ DEB formats or from xmlsoft.org.
+
+
+
+ Some editing tool. A popular one is Emacs with the psgml
+ mode. We have a intro to the PSGML
+ Mode in Emacs as part of our documentation. You can
+ read about other editing tools in the LDP Author Guide.
+
+
+
+ Writing New Docs
+
+ After you have the tools mentioned above, you need to define a
+ title for your document. Then start thinking about the possible
+ sections and subsections you will have in your document. Make
+ sure you coordinate with the OpenACS Gatekeepers to make sure
+ you're not writing something that someone else is already
+ writing. Also, if you desire to use the OpenACS CVS repository,
+ please e-mail the gatekeeper in charge of documentation.
+
+
+ You can look at some templates for documents (in Docbook XML) in
+ the sources
+ for acs-core-docs, especially the
+ Detailed Design Documentation Template and the
+ System/Application Requirements Template.
+
+
+
Document Structure
@@ -138,13 +198,12 @@
contains all the information above the line. This will be explained in more detail in a later document,
and we will provide a set of templates for documenting an entire package.
- For now you can take a look at the sources of these DocBook documents
+ For now you can take a look at the
+ sources of these DocBook documents
to get an idea of how they are tied together.
-
-
Headlines, Sections
@@ -578,46 +637,10 @@
<indexterm>,
<primary> and
<secondary>
- for this. See these links for an explanation and the
- source of this document
- for examples.
+ for this. See these links for an explanation.
-
-
-
- Tools
-
- You are going to need the following to work with the OpenACS XML
- documentation:
-
-
-
-
- Docbook XML
- DTD - The document type definition for XML. You can
- find an RPM or DEB package or you can download a zip file from
- the site linked from here.
-
-
-
- XSL
- Stylesheets (docbook-xsl) - The stylesheets to convert
- to HTML. We have been using a stylesheet based upon
- NWalsh's chunk.xsl.
-
-
-
- xsltproc - The processor that
- will take an XML document and, given a xsl stylesheet, convert
- it to HTML. It needs libxml2 and libxslt (available in RPM and
- DEB formats or from xmlsoft.org.
-
-
-
-
Converting to HTML
@@ -626,7 +649,7 @@
- Once you have the
+ Once you have the
installed, you can convert your xml documents to HTML (or other
formats. Let me know if you are able to convert to other
formats).
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml 13 Mar 2001 22:59:26 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml 30 Dec 2001 01:29:07 -0000 1.2
@@ -1,247 +1,247 @@
-System/Application Requirements Template
+ System/Application Requirements Template
-
-
-By You
-
+
+
+ By You
+
-
-Introduction
+
+ 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.
-
+
+ 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
-
+
+ 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.
-
+ 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
+
+ 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.
-
+
+ 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.
-
+
+ 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
+
+ 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.
-
+
+ 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
+
+ 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.
-
+
+ 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
+
+ Related Links
-Include all pertinent links to supporting and related material,
-such as:
+ 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)
-
+
+ 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
+
+ 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.
-
-
-
+
+ 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
+ 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.
-
+
+ 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.
-
+
+ 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.
-
-
-
-
+
+ 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 .
-
+
+ For guidelines writing requirements, take a
+ look
+ at the quality standards, along with a good example, such as .
+
-
-Besides writing requirements in natural language, consider using the
-following techniques as needed:
-
+
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ Entity-Relationship diagrams - a necessary part of Design
+ documents, sometimes a high-level ER diagram is useful for
+ requirements as well.
-
+
-
+
-
-Optional: Implementation Notes
+
+ 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.
-
+
+ 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
+
+ Revision History
-
-
-
-
-
- Document Revision #
- Action Taken, Notes
- When?
- By Whom?
-
-
+
+
+
+
+
+ Document Revision #
+ Action Taken, Notes
+ When?
+ By Whom?
+
+
-
+
-
- 0.3
- Edited further, incorporated feedback from Michael Yoon
- 9/05/2000
- Kai Wu
-
+
+ 0.3
+ Edited further, incorporated feedback from Michael Yoon
+ 9/05/2000
+ Kai Wu
+
-
- 0.2
- Edited
- 8/22/2000
- Kai Wu
-
+
+ 0.2
+ Edited
+ 8/22/2000
+ Kai Wu
+
-
- 0.1
- Created
- 8/21/2000
- Josh Finkler, Audrey McLoghlin
-
+
+ 0.1
+ Created
+ 8/21/2000
+ Josh Finkler, Audrey McLoghlin
+
-
+
-($Id$)
-
-
+ ($Id$)
+
+