Forum OpenACS Q&A: Encouraging Improved Documentation for OpenACS

I would like to open a discussion about improving the docs. Every other discussion always ends up unresolved. Noone has time to work on documentation.

We need someone to do this. It can be a community effort. I am going to setup a easy place for users to submit any sort of documentation. We can setup some guidelines as to the format and style, but I don't think we should be too picky. I will setup an ETP istance that allows user submission of the documents. Possibly it will have upload, but no guarantees.

Using this the documents will be indexed and hopefully users will be able to find them. If we are really lucky someone will compile them into something resembling actual documentation, but if not, at least they are all in one place.

So the main goal of this little idea would be to get everyone who has written up a cheat sheet for themselves to share with us all.

I won't have the ETP setup immediately. ETP 1.1 which won't have file upload, will be part of OpenACS 4.6.1, so when that is out, I hope to be able to work a little on the web site to get this going. In the meantime, please think about how you could contribute to this effort.

If anyone thinks this is a really bad idea, please come forward, so we can work out a better one.

The ultimate goal would be to have useful documentation for at least the core of OpenACS.

I also like the comments approach that we use at the bottom of: https://openacs.org/doc/openacs-4/db-api-detailed.html (for example).

This even gives the opportunity to upload a file, and will make it easier to integrate information with every new release.

The downside is that additional information will not be in one place. Time for a 'DOC Commit' forum, maybe... ?

But, whatever you decide, please give directions here: https://openacs.org/doc

First of all, I'd like to say that I think the doc team has done a pretty decent job considering the size of the job. So thanks to them for all their work!

But there have been many times when I've wanted to contribute little bits to the documentation, but the amount of work required to do so is higher than my desire to help.

If we had a Wiki, or the ETP instance for documentation, that would be excellent. For example, I was going through the notes example in the documentation, and ran into some problems and posted about it. Jon Griffin told me that the example was outdated, and to use ad_form instead. If it was easier for me to contribute to the documentation, I would have made sure the docs reflected this, so nobody else had to go through what I went through again. But alas, I'm not going to go read through how to do docbook, and/or submit the changes, etc...

I would be happy to help out with documentation if it were easier to do so.

Where:
If you think it would take more than an <include> to use /doc/openacs-4/ as a documentation-central, what about revamping and relocating https://openacs.org/4/ ? What exactly is it's status anyway?

How:
Allright you don't like general comments for this purpose. How about the Content Management System? Ouch..? I have never used it and I hear it is not easy, but could it be perfect (if it is ready)?

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.