OpenACS Documentation Standard

Introduction

There are basically three types of documentation needed for any modules that are written. They are:

• Developer/Programmer
• Administrator
• End User

History of ACS/OpenACS documentation

Ancient History

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:

4.x

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.

Specifics

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.

Developer/Programmer

• data model
• plsql
• tcl procs

Administrator

• What is there function in this module
• Admin page flow
• Additional admin options on user pages

End User

• Page flow
• Descriptions of form elements if not obvious

Common Elements

• Title
• Conventions
• Table of Contents
• Introduction (includes purpose)
• Design Goal
• Glossary
• Credits
• License
• Copyright
• Revision History

GNU Free Documentation License

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

Bookmark to: