Joel,
I like your documentation a lot! Great work! I'll print the docs and get back to you with more detailed feedback.
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)
