Forum OpenACS Q&A: Re: Would OpenACS be a good choice for my web site?
You have valid observations and somewhat incomplete conclusions. Hopefully these points address them.
OpenACS can appear more difficult than other platforms when one's background is mainly with the higher-level operations of applications, where end-user documentation is paramount.
You are right that this is a project biased to software engineers. One of the popular issues over the years has been if OpenACS is a web toolkit or a ready-to-use solution. Software engineers tend to appreciate the former, and end-users the latter. Advances in OpenACS (largely due to software engineers) are documented at the coding (api) level where coders use the documentation, and few other places. Efforts are made to address other documentation needs, but they have been more difficult than usual to 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
The community-based effort at documentation is most complete and accurate, and found here: https://openacs.org/xowiki/openacs-handbook
Software engineers are more likely to appreciate the relative ease in customizing it compared to customizing other platforms. That's why OpenACS appears as a blank slate. You can read more about OpenACS features for developers here: https://openacs.org/xowiki/docs-eng
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. That has been their experience. The community documentation above, is an effort to find balance that respects multiple perspectives that people are coming from.
Developers tend to be helpful when there is enough context provided with a problem for them to be able to diagnose it. More about getting help here: https://openacs.org/xowiki/docs-admin-help
cheers,
Torben
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!!!
