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.