1 26 Dec 2002 Joel Aufrecht Consolidated and shortened existing OpenACS documentation; added some ideas from Construx 0.3 5 Sep 2000 Kai Wu Edited further, incorporated feedback from Michael Yoon 0.2 22 Aug 2000 Kai Wu Edited 0.1 21 Aug 2000 Josh Finkler, Audrey McLoghlin Created ($Id: package-documentation-template.xml,v 1.1.2.1 2003/04/07 16:25:51 joela Exp $) Your Name

youremail

This package does .... Summarize the rest of this document in one paragraph. The components of this package are ... List the major components and their functions. This package depends on ... List other packages, other software, and any external processes that the package needs. Define any abbreviations or other special terms. List some people who would use this package. Describe how they would use it, how it would be better than what they are doing now, and how it compares to alternatives. Include specific, real sample data if possible. This user will accomplish X with the package. Currently, the user does X with product Y, which takes several hours and costs too much. User 1 adds and edits stuff ... User1 Views stuff ... An example of data stored in the package is ... A list of requirements, split up into functional areas. In the ideal requirements document, all requirements are sufficiently specific, detailed, precise, and comprehensive that the package can be designed and built without any other directions, and two different packages built to meet the same requirements will be similar internally and have identical APIs. Requirements are prioritized relative to a release cycle. All priority A requirements must be satisfied before the package can be released. Priority B requirements are desired but should be cut as soon as possible if the schedule is threatened. Priority X requirements should not be implemented in this cycle; at the beginning of the next cycle, they should be promoted to A or B or removed. Describe all of the interfaces between the package and other OpenACS packages, the OpenACS API, the host computer, and network clients. Include sample conversations for any external APIs. Describe any API the package will provide. General description. Number Priority Description 100AA critical requirement. 110BAn optional requirement. 120XA requirement deferred for this cycle. Use storyboards and drawings to describe what a typical user will see and how User 1 will use the product. This includes web interfaces, email. What will have to change in a typical installation? What are reasonable defaults? How sensitive is the data stored? Can users see or edit each other's data? What cryptography is required? What logs should be kept, who should monitor them, and how? 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. 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. Description of table. Field Description Relationships Type Sample Value fieldname Indicates ... Primary Key... References ... int 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. Under OpenACS 4.5, 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. 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. Documentation for an end user. No administrative tasks are needed or possible Construx Software Builders, Inc. 2002 Construx Software Builders, Inc. 2002