Hazi Gharagozlou, Ramiro Gomez, Heiko Kern, Peter Marklund
Summary of Discussion:
All participants recognized that the current documentation for OpenACS is outdated and very difficult to use for a newbie. (I mentioned that I couldn't use ETP because of its documentation). All recognized that Joel Aufrecht's efforts is appreciated and a good path to follow.
The group recognizes that there is a need for three levels of documentation:
- User's guide
- Admin guide (Managing a site)
- Developer's guide
It should enumerate all functionalities of a package/module. The parts this document can also be used as link in pages for content-sensitive help (Lars mentioned it as important in his UI discussion). A walk-through of some of the typical user cases would be helpful to clarify obscure functions.
Currently we assume admin tasks to be carried out by a developer. However in a large organization an administrative assistant should be able to handle some of the mundane tasks. The role can be called site or sub-site manager. The manager would handle user/group creation and permissioning system.
There is some doubt on whether the manager should also manage packages and mounting sub-sites.
Developer guide should be up to date. Perhaps we can use ad_library comments more effectively in developer's document instead of searching for it in API browser.
Finally mention was made of difficulty of using Emacs with all the bells and whistles and bringing all together in a Docbook format.
Recommendations and Decisions:
- Decision to discuss with the Docbook experts in the community (Roberto?), on using other document formats like MS Word, and then using a filter to incorporate the document in a centrally located Docbook project.
- Afterward I spoke with Don Baccus and convened that when he supplies me with a few complex examples of group permissions (i.e. roles), I am willing to write up a mini how-to and change the UI of group management (hopefully making it easier to use)
- The developer documents should contain ER and Page flow diagrams.
To start the effort I have reversed engineered the OpenACS 4.6 Oracle data model and I am posting the first effort on File Storage.
I will update the diagrams as new versions of OpenACS become available(Already obsolete with the release of 4.6.2!)