Powered by Max Banner Ads
There are basically three types of documentation needed for any modules that are written. They are:
- End User
History of ACS/OpenACS documentation
In the beginning there was a quasi standard for a documentation page. Although not a formal specification, it was an unwritten rule that at least some documentation was released with all the “modules” in ACS.The major sections of this documentation were as follows:
Starting with the ACS 4.x release, ArsDigita decided that it was time to take documentation serious and embarked on standardizing on a format. It was also decided that no package would be deemed release ready until this documentation was complete. A committee was formed and a documentation standard was agreed upon.The committee decided that 2 basic documents were needed to satisfy the documentation needs. These were the System/Application Requirements and the Detailed Design Document.
My feeling is that the documentation provided, while certainly of some use, is generally not friendly and tends to be geared towards the developer. The thinking seems to be getting the package design done before programming, which was in sharp contrast to the way ACS was developed before 4.xI propose the following sections. Much of this was adapted from looking at other documentation as well as my own and others ideas.
- data model
- tcl procs
- What is there function in this module
- Admin page flow
- Additional admin options on user pages
- Page flow
- Descriptions of form elements if not obvious
- Table of Contents
- Introduction (includes purpose)
- Design Goal
- Revision History
GNU Free Documentation License
This document is Copyright © 2002 Jon Griffin.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.