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$) + - -