Forum OpenACS Q&A: Documentation cleanup suggestion.

It will greatly reduce the amount to be maintained.

• Development Reference
• Engineering Standards
• Kernel Documentation

http://www.infiniteinfo.com/openacs/things2remember.html

This info could help on updating the freebsd docs  (and perhaps integrating them into the linux docs):

https://openacs.org/forums/message-view?message_id=51195

https://openacs.org/forums/message-view?message_id=51126

Also, I  think it's time the doc-associated forums are created as discussed in:

https://openacs.org/forums/message-view?message_id=44661

As a newcomer to OpenACS, I have to say that I feel exactly the opposite way of your assumption. I want MORE documentation! hehe. I found the existing docs to be a good overhead view of the system, and there is a vast amount of older documentation out there (old ACS Journal articles, and Phil G's books), but that documentation doesn't seem to be relevent to the current state of OpenACS. It helped me to get a good bird's eye view of how it all works, but I want more specifics and cookbook / howto type docs.

Joel's recent developer doc on creating packages was very nice.

As an example of good documentation, I really have to say that PHP and MySQL's websites have very nice documentation with user feedback that often includes more valuable content than the original documentation. In general they both have an organized reference manual and each page has loads of user feedback with examples, gotchas, work-arounds, etc. Can something like that be created for OpenACS?

If I knew more about OpenACS then I'd step up to the plate and create that.

Ability to comment on the docs is quite important. I don't know how people currently comment static pages. Is there such a solution in OpenACS already? I notice that there is a page package and a static-pages package. Of those the latter seems more sophisticated. Which one should we use? Fetching the comments from openacs.org to a local server wouldn't be difficult once we have commenting set up at openacs.org and every page is identified by a uri.

A few things I think should be in your tutorial are:

1) A few recommended example packages for people to look at. I am thinking the logger package I am developing now might become such a package as it is a relatively small and simple package and hopefully we can make it reflect best practices. It doesn't use CR though.

From point 1) developers can see much of the following:

2) How to group Tcl procs in namespaces.
3) How to make package instances deletable via the site-map and uninstallable using the APM UI by utilizing the before-uninstantiate APM callback.
4) That -procs.tcl files should *only* contain ad_proc statements.
5) That server startup tcl code (scheduling of procs, filters, nsv variables) should live in -init.tcl files in the same tcl directory.
6) That create and drop scripts must follow a naming convention and should source separate table and package scripts.
7) That Tcl API test cases should live in a file named tcl/test/package-key-test-init.tcl and that test support procs can live in -procs.tcl files in that directory.
8) That to use such tests acs-automated-testing must be installed and mounted.
9) That each table in the datamodel should have a comment
10) That each ad_proc should have well written @param and @return tags (i.e. the contact of the proc should be explicit)

Here is some more documentation feedback.

I found the section with Ola's suggestion a little confusing.

What does samplenote::new mean? It's not really explained anywhere, or linked in anywhere.

I'm fairly familiar with ACS, and have used OpenACS a little, and I found that section totally mysterious. Where does that definition come from? Is it a namespaces thing? I'm not really up on namespaces.

Anyway, I imagine some more explanation might be in order there. I'd offer concrete wording suggestions, but I don't understand it yet. 😊