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
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.
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
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
cover sheet (the cover sheet is a wrapper doc with links to all
other package docs).
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.
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
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
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 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.
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:
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
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.
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.
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.
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 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.
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
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
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
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.
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 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.
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"
section can greatly facilitate the documenting of this section.
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:
System creator
System owner
Documentation author
Revision History
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?
0.3
Edited further, incorporated feedback from Michael Yoon
9/05/2000
Kai Wu
0.2
Edited
8/22/2000
Kai Wu
0.1
Creation
8/21/2000
Josh Finkler, Audrey McLoghlin
($Id: design-template.xml,v 1.2 2001/12/30 01:29:07 rmello Exp $)