Design Documentation Template

by Joshua Finkler and Audrey Mcloghlin

I. Essentials

When applicable, each of the following items should receive its own link:

User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
Requirements document
Design document
Data model
PL/SQL file
ER diagram
Transaction flow diagram

II. Introduction

This section should provide an overview of this system and address at least the following issues:

What this system is supposed to allow the system user to accomplish.
Within reasonable bounds, what this system is not intended to allow the system user to accomplish.
In which sort of applications this system is most likely to be of use.
A high-level overview of how the system meets the design requirements. This is to include relevant material from the "features" section of the cover sheet.

Also worthy of treatment in this section are the following issues:

When applicable, a careful demarcation between the functionality of this system and other systems which at least superficially appear to address the same requirements.

Note that it is entirely possible that a discussion of what a system is not intended to do might differ from a discussion of future improvements from which the system might benefit.

III. Historical Considerations

When designing a software solution to meet the constraints of a fixed set of design requirements, it is almost always the case that many possible mutually exclusive solutions are given consideration. Although eventually only one solution is implemented, a discussion of those alternative solutions canvassed during the software design process, with special attention paid to the reasons for which these alternative solutions were rejected, should ultimately prove quite helpful to future developers and will help ensure that no time is wasted on the analysis of problems already solved.

IV. Competitive Analysis

Although currently only a few system documentation pages contain a discussion of the features of software which competes with the ACS system at issue (e.g., chat, portals), this should be an essential feature of the documentation for any system for which there exists competing software.

If the system exhibits features missing from competing software, this fact should be underscored.
If the system lacks features which are present in competing software, the reasons for this should be discussed here; our sales team needs to be prepared to handle inquiries regarding features our systems lack.

Note that such a discussion need not be coextensive with a discussion of a system's potential future improvements.

V. Design Tradeoffs

No single design solution can optimize every desirable system attribute. For example, an increase in the security of a system will entail a decrease in the simplicity of the system interface, and an increase in a the flexibility of a system typically entails a decrease in the simplicity of the structure of that system. As a result, 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 this choice. Some areas of importance to keep in mind are:

VI. Data Model Discussion

The data model discussion should do more than merely display the SQL code for creating the relevant tables and sequences; this information should already be readily accessible via a link in the "essentials" section of the documentation. The discussion should constitute a high-level treatment of the primary entitites and main transactions relevant to the data model.

The data model discussion should address the intended content of each table column when this information is not perspicuous from an inspection of the data model itself.
Block copies from the data model should only be done adjacent to a discussion of the particular constraints imposed upon the data structure by that portion of the data model.
If an auxiliary system is being employed for table maintenance (e.g., the new group and scoping system, general comments, et cetera), this should also be mentioned.
Any default permissions should be identified herein.
If the data model contains extensions which can tie into other systems, this should be discussed here.

VII. Legal Transactions

This section should include a discussion satisfying each each of the following points:

Any modifications which the database may undergo as a result of employing the system under consideration should be discussed here.
Any considerations pertinent to that particular data model and ensuring table integrity should be highlighted at this point.
Legal transactions should be grouped according to the location of the files which perform the relevant data modifications, e.g., separate treatments for those data modifications which can be performed from the /admin pages for the system and those which can be performed by an ordinary community user on a system employing that system.

VIII. API

This section should include a discussion of the particulars of the database API used to provide an abstraction barrier between the system code and the underlying core software, typically so as to help minimize unnecessary repetition in the system code. Although this information may be covered in more general detail in other sections of this document, this section is the appropriate place to discuss the details of each of the procs employed in the development of this system, including each of:

algorithms,
transactions, and
UI.

Historically, the relevant procs have been encapsulated in a TCL file, however the current engineering effort encourages developers to avoid this practice. 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 future instantiations.

IX. User Interface

This section should offer a discussion of any user interface considerations relevant to each of the three classes of intended system users:

Developers
Site-wide administrators
Sub-site administrators
User

In order that developer documentation be uniform across different system documents, these users should herein be designated as "the developer", "the administrator", "the sub-admin", and "the user", respectively.

Note that as our templating system becomes more robustly entrenched within the ACS, the details within this section are likely to shift from UI specifics to template interface specifics. Areas of interest to users:

Performance: availability and efficiency
Flexibility
Interoperability
Reliability and robustness
Usability

Areas of interest to developers:

Maintainability
Portability
Reusability
Testability

X. Configuration/Parameters

This section should discuss the parameters the user will need set in their .ini file in order to successfully employ the system. Discussion should focus on those parameters which may not be entirely perspicuous to a first-time user attempting to employ the system.

XI. Acceptance Tests

Although this information is available in a more comprehensive ACS installation document, a user new to a system should not be forced to wade through this entire document merely to ensure that they have their implementation of this system up and running. Ideally, this section will contain the relevant information from the larger document enabling acceptance testing of just this system. At a minimum, however, the document should contain a link to this section of the larger acceptance test document.

XII. Future Improvements/Areas of Likely Change

If the system lacks features which would be advantageous in the long-run, this should be noted here. Also noteworthy herein are ease-of-use considerations (e.g., UI and/or templating issues) not necessarily involving a system feature.

Note that a careful treatment of the earlier section entitled "competitive analysis" greatly facilitates the carrying out of the present section.

XIII. Authors

Although a system's data model file often contains this information, this does not hold true in general. Furthermore, data model files have often undergone substantial revision, making it difficult to track down the system creator from this information. Complicating matters, system documentation occasionally is authored by people not directly involved in the system creation process. Regardless of whether or not system ownership can be determined by appeal to these files, new system users should not be subjected to such a search simply in order to have access to some basic information about the history of system, such as system origin. Thus a mail link to the following should be included in each developer document:

System creator
System owner
Documentation author

jfinkler@arsdigita.com
audrey@arsdigita.com