Forum OpenACS Q&A: Re: Encouraging Improved Documentation for OpenACS

My perspective on the current docs as a newcomer to OpenACS will probably not come as a surprise to anyone here: There is room for improvement. As I explore deeper I am constantly surprised by the amount of effort that has been put and continues to go into the toolkit, and what can be accomplised by using it. Sometimes I feel a bit like surely there must be some dirty secret hidden somewhere, which is the reason why the toolkit isn't in more widespread use. But apparently the steep learning curve is one of the few reasons for this peculiarity.

Adding large documents like the install docs is a daunting task not to be taken lightly, but if some mechanism was available, where one could add small pieces of key information in an orderly fashion, then I would definitely like to be one of the contributors. Not the least beacuse that is one of the few areas I would feel comfortably about contributiong at my current level of experience. Not much harm would be done if I was to make a serious mistake, as opposed to contributing directly to the CVS repository.

As for the notes packages and similar situations, then I would rather be completely without example code, than possibly wasting time going down the wrong path. Ie. outdated docs ought to be unceremoniously deleted, or at the very least clearly tagged as such IMHO.

The current state of the docs, where they are scattered all over the place without a central links page, is doubly unsatisfactory. Because there is no central place (that I have found) with links to everything useful out there, I am constantly wondering if info on an issue I may be struggling with is buried here somewhere, and if I perhaps simply haven't found it yet.

Also the missing link issue to some degree personally makes me hesitate to ask a question on the fora out of fear of being told about the 'obvious' place for the docs in question. Searching the fora often yelds good results, but how do you determine if the info is outdated or still current if a thread is 2 years old? Short answer: You don't.

The bug tracker is useful for giving feedback to some of the more monolithic documents. Yet there are many other subgroups of usefull info that the community could benefit from collection from its members in piecemeal fashion, that I don't think will fit into that mechanism. Wether the collection should be via Email as the current FAQs or through a web interface is of less importance. Some examples of subject groups I believe a newcomer would find usefull and interesting are given below (in no particular order):

• Performance tuning: Linux and *BSD userspace/kernel limits, patching PG for 16kb BLCKSZ, moving pg_xlog to a different spindle.
  
  
• ISO-8859-1, Unicode and other i18n issues: Setting correct environment variables, PG compile time options.
  
  
• Optimal way of localizing and customizing packages, thus allowing people to track bug fixes in the core code.
  
  
• Minimum hardware requirements: I guess running OpenACS on my old P133/64MB testbox is technically possible, but it would hardly be very fast, nor give a good impression of the toolkit. However a recent P-III or P4 workstation with a 7200RPM IDE disk and 256MB+ of memory appears to be a good development machine. I don't think I would like to run the toolkit on a production machine with only 128MB of memory as Vinod's installation doc suggests. This subject also ought to cover the virtues of using ECC memory and fast SCSI disks, multiple spindles etc.
  
  
• Scalability issues: How does the OpenACS core tools and individual packages scale with the size of the community, number of objects etc.?
  
  My main application for OpenACS is for building a common community web infrastructure for a number of small not-for-profit orgs, each of which will get their own subsite with their customized web design and so forth.
  
  One of the people I work with on this project have come up with a, to them, very interesting application that will require some 1000+ users to register, in combination with a table of considerable size, giving a relation over time between said group members.
  
  Unless I find a way to optimize the relation and break it down in smaller tables, then the table will need to have around 1 million rows or so. Do I even want to go there using commodity hardware? My informal PG tests suggests I wouldn't have a problem if I have enough memory to cache the whole table at once as most transactions will be read queries, but I do wonder what happens once the hooks into the OpenACS infrastructure are added.
  
  
• Proxying AOLserver behind Apache, including a HOWTO. Why this may be a (not so?) great idea: mod_gzip for the bandwidth impaired sites (yes, I know about rl_returnz), HTTP/1.1, running several instances of AOLserver at once, all reachable via port 80. Security issues by doing so?
  
  
• A link collector with links and a short description of the contents of the document linked. Many OpenACS developers have their own FAQs and documents, which ought to be linked from a central place.
  
  
• A code snippet cookbook for beginning templating/Tcl pilots. There are some in the templating docs, but more would not go amiss, especially less so if they included some not-so-obvious SQL + PL/[pg]SQL constructs in the context of the OpenACS architechture.
  
  
• More general "building web communities HOWTO's". Structuring a web community so it doesn't confuse users, planning for future expansion, generally useful tips and tricks etc.
  
  As an example belonging to the last group is a simple thing that may help sites on a low bandwidth connection: I generally prefix all links to static graphic design elements with a configuration variable called '@fn_gfx_base@' or some such, while at the same time keeping the graphics in a separate, parallel tree on the disk. This allows all non-dynamic graphics to be eaily copied to and located off site at your friendly telco with a fat pipe, thus conserving your local bandwidth and server resources.
  
  Also belonging here are things like why you want to supply all graphics design elements and, if possible, user contributed graphics and photos with WIDTH, HEIGHT and ALT tags, plus inlining your style sheets as opposed to having them in separate files.
  
  
• Workarounds for bugs and other gotcha's like the PG 7.2.3 pg_dump issue and getting the preferred AOLserver 3.3.1+ad13 to compile on FreeBSD.
  
  
• OpenACS advocacy: Why and where you may want to use OpenACS and what you will get once you get through the long installation process.

The general idea here is that all of these subjects can either be a single bullet in a FAQ, or a list of same. Some will be a textual description, while others can simply be a link to a page with more info on a given subject. Outdated examples and items can be deleted as needed and new ones easily added or edited when a new gold nugget surfaces in the fora, or as experience is gained.

The other side of the coin is that I as a newcomer and newbie doc contributor indirectly could use this as a way of testing the knowledge gained, and as an opportunity to learn more if the work was under the supervision of some of the experienced developers. If the solution to a question is found OK by the community, then great. If I have completely missed something, then I am bound to hear about it, which is great too.

So basically I think this is a great idea, Dave.

Frank.