Forum OpenACS Q&A: Re: Would OpenACS be a good choice for my web site?

I'm going to try one more time to reply via e-mail. If that fails, I'll have to cut/paste this into the forum, so please forgive any format mangling if I have to do so. Did the server move break the notification e-mail reply system in addition to the IRC log system?

Would an OpenACS mailing list be too much to ask for? Mailing lists are so much easier to keep up with than online forums.

On Wed, 20 Aug 2008, mailto:torben@dekka.net wrote:

You have valid observations and somewhat incomplete conclusions. Hopefully
these points address them.

Your points might help. Then, again, they might help further exemplify our incomplete conclusions. Sorry, I don't mean to be difficult. I see a lot of potential in OpenACS. If I could just find a few examples showing
how to get started and demonstrating current best practices, it would be great.

address. Read more about the history here:
https://openacs.org/xowiki/doc-history and coordinated efforts and addressing
it here: https://openacs.org/xowiki/Documentation_Project_Plan

Following a link on the above page to the Documentation Requirements for Developer Tutorials page:

https://openacs.org/xowiki/docs-dev-tutorial-reqs

It looks like the OpenACS community realizes the kind of tutorial I'm asking for is needed. And, it looks like they realized that back in 2003. I think the most important point listed is:

* Provide working examples that highlight the various subsystems, tcl environment ....

And, the key words in that point are ***working examples***. And, it should probably be changed to read: working examples of current best practices. The current developer tutorial isn't a working example. If one installs the current version of OpenACS, and then tries to work through the developer tutorial, the first thing that will fail will be the SQL drop script. If they're lucky enough to find the patch to get past that problem, there's at least two other problems, if I remember correctly. If one follows the "quick start" instructions on the first
page and just copies the code, only one more patch is needed to get it to work. Sorry, I don't have my notes handy right now, but I'd be happy to nit-pick my way through the tutorial again and note all the problems and
fixes I found. The quick start instructions have one copy note-procs.tcl from packages/acs-core-docs/www/files/tutorial . If one instead chooses to work through the tutorial step by step, it has one copy note-procs.tcl from packages/acs-core-docs/www/files , which is a slightly different version of note-procs.tcl, which doesn't work. If one takes the step by step route and copies note-procs.tcl as instructed in that part of the
tutorial, they'll get an error saying the required id parameter is missing when trying to add a note. In the version of note-procs.tcl copied via the quick start instructions, the add proc doesn't require an id parameter. The version copied using the instructions in the step-by-step tutorial requires an id field.

The community-based effort at documentation is most complete and accurate,
and found here: https://openacs.org/xowiki/openacs-handbook

Okay, it looks like there might be a bit of good information there. If I follow the link from that page to:

https://openacs.org/xowiki/docs-dev-tutorial

The very first link to an actual tutorial on that page points to the outdated buggy developer tutorial:

https://openacs.org/doc/current/tutorial.html

Some of the other links contains some bits and pieces of info, but I don't see anything resembling a complete tutorial as described at:

https://openacs.org/xowiki/docs-dev-tutorial-reqs

If I'm missing one somewhere, please point me in the right direction.

The openacs.org website is confusing because it is controlled by a pool
of developers, each with their own ideas. They rarely visit the parts of
the website that end-users do. They are unwilling to give publishing
control of the website to end-users who likely don't appreciate their
needs and the needs of the development initiatives of the project.

So? That might be a reason for the website being confusing, but it's not a valid excuse. Someone in the OpenACS community who has publishing control of the website needs to take charge and make an effort to keep the parts of the website that end-users visit up to date.

That has been their experience. The community documentation above, is an
effort to find balance that respects multiple perspectives that people
are coming from.

That's great, but coordinate the effort. If an up-to-date developer tutorial is created somewhere on the xowiki, change the developer tutorial link on the front page of the web site so that it points to it instead of the outdated buggy tutorial. It's not a difficult concept.

Kevin
http://www.RawFedDogs.net
http://www.WacoAgilityGroup.org
Bruceville, TX

Si hoc legere scis nimium eruditionis habes.
Longum iter est per praecepta, breve et efficax per exempla!!!