Forum OpenACS Q&A: OpenACS Technical Documentation

Collapse
1: OpenACS Technical Documentation
Posted by Alfred Essa on 11/03/05 11:24 PM
In the Why Use OpenACS, we run across the following assertion:

"Excellent Documentation

Unusual among open source projects, the OpenACS is very well documented. Community members are encouraged to document and distribute their new packages as well as address any lack of information in existing documentation."

I wonder if this assertion still stands true. Some parts are well documented but others are poorly documented. It appears that application packages and individual modules are either out-of-date or not documented at all. Without proper documentation it makes it difficult, nearly impossible, for us to build on each others work. It also keeps the "knowledge" locked in the hands of a few, thus defeating the whole purpose of working in an open source effort. Having access to source code and the freedom of an open source license is important, but we don't leverage each other's work unless each person and organization is also making incremental investments in documenting the code.

How can we encourage everyone to invest more time and effort in documentation?

It might be worthwhile to review some good models going back to the ars digita days:

http://philip.greenspun.com/doc/

For starters, take a look at the documentation for chat:

http://philip.greenspun.com/doc/chat

The documentation provides rationale (why), approach, and data model. Shouldn't every application module have that as a minimum? And when someone makes a non-trivial change, shouldn't the documentation be updated?

Thanks for listening to my rant.

Collapse
2: Re: OpenACS Technical Documentation (response to 1)
Posted by Malte Sussdorff on 11/04/05 10:04 AM
Hi Al,

you are true in your assumption, but this is what we have maturity levels for. The core is well documented, though we are in desperate need for a new way of documentation (and I think the wiki is the key here).

As for the packages, reality is that you first develop and then write the documentation. Preferably you should do it the other way around, but well. cognovís does a mixed approach whereby we are using a short description which we agree to with the client (feature list and rationale) which we then turn into code and after that into documentation. As our contracts usually last for quite some time, the lack between the code and the documentation is fairly huge.