Documentation History

The history of OpenACS documentation: ..began by building on a good documentation base from ArsDigita's ACS in the late 1990's. The ACS documentation was largely written in docbook. Some sections of the documentation, however, lacked details and examples; others simply did not exist. The OpenACS community began meeting the challenge by identifying needs and writing documentation on an as needed basis.

By having documentation dependent on volunteers and code developers, documentation updates lagged behind the evolving system software. As significant development changes were made to the system, existing documentation became dated, and its value significantly reduced. The valiant efforts that were made to keep the documentation current proved too difficult as changes to the system sometimes had far-reaching affects to pages throughout the documentation. System integration and optimization quickly rendered documentation obsolete for developers. The code became the substitute and source for documentation.

There are many thousands of lines of code, and few developers tracking changes and publishing the changes. Subsequently features and advances to the OpenACS system went unnoticed or were not well understood except by the code authors. Work was duplicated as a consequence of developers not realizing the significant work completed by others. New developers had to learn the system through experience with working with it and discussion in the forums. Informal sharing of experiential and tacit knowledge has become the OpenACS community's main method of sharing knowledge.

Around 2006, efforts were made to build a consensus in new ways to overcome existing documentation limitations. Like most any diverse community, a consensus could not be reached. Time has distilled efforts into three approaches that augment OpenACS' primary source of documentation: OpenACS code itself.