Index: openacs-4/packages/acs-core-docs/www/filename.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v diff -u -r1.40.2.8 -r1.40.2.9 --- openacs-4/packages/acs-core-docs/www/filename.html 17 Jan 2006 03:44:38 -0000 1.40.2.8 +++ openacs-4/packages/acs-core-docs/www/filename.html 9 Apr 2006 22:26:13 -0000 1.40.2.9 @@ -1,4 +1,5 @@ -Detailed Design Documentation Template

Detailed Design Documentation Template

By You

Start Note

+ +Detailed Design Documentation Template

Detailed Design Documentation Template

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 @@ -10,19 +11,19 @@ your own judgment, consult with peers when possible, and adapt intelligently.

- Also, bear in mind the audience for detailed design: fellow + 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: -

  • 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

Introduction

+

  • 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

Introduction

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.

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

  • 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 + 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: @@ -32,15 +33,15 @@ 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. -

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. @@ -51,7 +52,7 @@ lacks.

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 @@ -61,7 +62,7 @@ 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:

  • Performance: availability and efficiency

  • Flexibility

  • Interoperability

  • Reliability and robustness

  • Usability

Areas of interest to developers:

  • Maintainability

  • Portability

  • Reusability

  • Testability

API

+

Areas of interest to users:

  • Performance: availability and efficiency

  • Flexibility

  • Interoperability

  • Reliability and robustness

  • Usability

Areas of interest to developers:

  • Maintainability

  • Portability

  • Reusability

  • Testability

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 @@ -79,10 +80,10 @@ 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. -

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 + "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 @@ -93,10 +94,10 @@ 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.

  • Any default permissions should be identified herein.

  • Discuss any data model extensions which tie into other - packages.

  • Transactions

    Discuss modifications which the database may undergo from + packages.

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

  • User Interface

    + subsite-admin, by a user, by a developer, etc.

    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:

    @@ -107,32 +108,32 @@

    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," + "the developer," "the OpenACS-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. -

    Configuration/Parameters

    - Under OpenACS 5.2.2, parameters are set at two levels: at the global level by +

    Configuration/Parameters

    + Under OpenACS 5.2.3b1, 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. -

    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.

    - Note that a careful treatment of the earlier "competitive analysis" + 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: -

    Revision History

    +

    Revision History

    The revision history table below is for this template - modify it as needed for your actual design document.

    Document Revision #Action Taken, NotesWhen?By Whom?
    0.3Edited further, incorporated feedback from Michael Yoon9/05/2000Kai Wu
    0.2Edited8/22/2000Kai Wu
    0.1Creation8/21/2000Josh Finkler, Audrey McLoghlin
    ($Id$)
    View comments on this page at openacs.org