Why a reluctant coder chooses OpenACS in spite of imperfect documentation

inside a round building where concave walls are covered in full bookshelves

image (CC BY 2.0) by Leoboudv @ Leoboudv

This post is a continuation of a series on critical reviews by coders of OpenACS. And, what it means as a reluctant coder.

Review: Poor and incomplete documentation. End users don’t speak geek or want to know about TCL and database support. Things like metadata for tables have several different partial solutions in different places et cetera.

As OpenACS evolves, generating useful documentation remains an ongoing issue and discussion topic. Useful topics hide throughout the forums, faqs, file storage etc. Efforts are underway to summarize these jewels and add more. Much of OpenACS documentation is directed to software engineers because of historical reasons. ArsDigita (aD) created early versions of the ACS framework. They were writing for engineering students, where code is the documentation for the most part. ADUni.org holds much of the original content of aD University.  Prior to aD, the NaviServer/Tcl framework was deployed by teams for utility scale media providers, such as DigitalCity.com and AOL.com delivering dynamic content to subscribers.

As a reluctant coder, this means that the documentation is available to go as deep into the infrastructure as you need. Still, new developers need documentation to transition or translate engineering “geek speak”.  Small-time operators looking for an expanded blog or site builder with some built-in features don’t want to have to learn about the entire system internals. This kind of documentation is being written by other reluctant coders in an OpenACS handbook with you in mind. When you ask a question in the OpenACS.org forums, you are contributing to new documentation.

Review:  It’s impossible to install OpenACS in a day.

OpenACS can now be installed on popular distributions within minutes. Scripts are published that automate the process. Developers are keeping OpenACS closely matched to the default environments of software it depends on.  This reduces the likelihood of running into an issue during installation on any platform that supports its components.

As a reluctant coder, know that one version of the installer allows significant customization to the installation script, so that you don’t have to make adjustments to configuration parameters after installing.  Just trigger the install scripts and then start your site’s NaviServer.