Forum OpenACS Q&A: Response to Newbee documentation

Collapse
Posted by Torben Brosten on

Aldert and Ben, thank you for the thoughts on forum management. Note that this thread has nothing to do with the upcoming forums and how they will/should work. If anyone wishes to continue on the topic of forum operations, please start another thread.

Aernout, I am learning that the documentation presentation is very much tied to a chronological sequence. Deviating from the sequence will likely slow learning significantly, since access to some very useful documents and information depends on having a locally installed and working system. Here is the sequence as I understand it:

  1. read about the system in general
  2. install the system
  3. read more about the system via the installed and working system
  4. confirm one's understanding through experimentation (trial and error) on a local system, and digging through the code

The working system has some instructions presented in context with where the commands are issued --in the User/Admin Interface (UI) starting at http://your-local-installation/ . Also, package documentation is accessible via the web at http://your-local-installation/doc/

Others have recommended strongly "installing the system and giving it a whirl" etc. but I did not really understand why. I thought it was evangelism for the system, not due to a set sequence of access to documentation. My learning style is grounded in reading about something in great detail, and understanding it, before trying it. OpenACS documentation precludes this approach, perhaps for a good reason: there have been periods of rapid development, where documentation and code have evolved in significant increments. The labor associated with posting documentation for all versions, and maintaining them, has been avoided by connecting the documentation directly to each installation/revision. As development stabilizes, an "official release" is designated (and some documentation published). I would have learned much more, sooner, had I installed a local OpenACS 4.x pre-beta instead of waiting...

Thankfully, a significant portion of this information is now available prior to installing. See "Documentation for this installation of OpenACS" ( https://openacs.org/doc/index-3.html ) from https://openacs.org/doc/ This is great if one does not time or resources to dedicate to installing, but wants to find out more about the system.

Still, at this point, beginning developers will gain much from a working local installation.