[Zope] Giving up in frustration

Joe Grace occam@serv.net
Mon, 16 Aug 1999 14:16:34 -0700


Hadar Pedhazur wrote:

> I guess you thought better of helping the community (and
> yourself) out over the weekend. Too bad. Someone with your
> qualities:
>
> "I'm experienced, quick-witted, hard-working, dogged and
> persistent."
>
> could have added a laser-like focus to the sections that
> most need updating.
>

Wow, does this jab seem unfair.  I completely sympathize with the
original poster, but I also sympathize with DC.  What I don't sympathize
with is patronizing comments (and unwarranted insults).

Look, writing authoritative documentation is non-trivial and not
typically for novices to a technology.  It also takes confidence,
motivation, and copious amounts of spare time.  I don't think it's fair
to ask someone to write docs for something which they barely understand
(and might be embarassed with getting wrong).  Where's the good in that?

The novice's job is to get up to speed as rapidly as possible with all
the basics so that s/he can really get stuff done as soon as possible.
That's the best support Zope can ask for from newbies.

Unfortunately, without up-to-date and complete basic documentation,
that's very difficult.

I've wasted *days* due to oversights in Zope documentation.  I didn't
know enough to know that something was missing, but I did know I was new
to Zope and had no right to believe Zope had bugs in such basic stuff
(which it didn't).  Eventually, I came around to questioning the
documentation.

I believe the original poster *is* contributing back to the Zope
community if nothing more than simply to red flag a problem area.  Be
happy he cared enough.

-=-

That said, Zope seems largely self-documenting once you get to know it
(which I don't).  Also, the design seems so well thought out that new
approaches *replace* old approaches with better solutions.
Unfortunately for newbies, Zope is in a transition where things have
moved, documentation is outdated, and multiple 'competing' technologies
do similar things.  Where does a newbie start?  The experts know the
correct and idiomatic ways to do things, but the newbies can get lost.
I know because I've been looking for some basic information for some
time without results (either to posts or in the docs).  I would get
totally frustrated too except I've had some insane luck getting some
good stuff working (eventually).

Now, I'm trying to upgrade to another level of Zope knowledge, and I
know the docs are incomplete (from my previous experience with them and
now that I know enough to wonder "Where did you say that file belongs?
Doh, you didn't.")

Ok, here's one big suggestion for Zope.  Include in the initial Zope
database, all the example projects from the docs (but in a sample
directory which won't get in the way of trying to install the
documentation examples as written).  That way, newbies don't have to
learn how to put the projects in the database before experimenting with
them.  Also, if the installation goes wrong, the newbies have a running
example to compare against to see where they went wrong.  Then document
the heck out of the installation procedure.  Also, create all the file
system directories necessary for the documentation projects to be used,
e.g., Extensions, etc, as part of the basic Zope installation.  Finally
put README's in those directories explaining what the files there are
for (samples, examples, etc., and links to relevant documentation).

I might also suggest a more radical change which would be to put all the
user modifiable directories in their own branch (I know, may not
dovetail with basics of Zope pathing, etc.).  These would include: var,
Extensions, Products(User), etc..  This way, all customizable
directories are readily located... and a Zope installation can be copied
and dropped into a new version of Zope no problem, or backed up, etc..
This suggestion may be nonsense from a cleanliness perspective.  Perhaps
just better documentation.

I'm also interested in doing docs but I've found it difficult to get
responses reliably.  It's pretty hard to get up a head of steam in a new
complex system without a mentor or fast turnaround on simple questions.
So, I'd say the Zope community is still suffering some growing pains,
and losing potential Zope'rs may just be a symptom of the current stage
of growth and focus on serious new features.

-=-

Bottom line: give the guy a break.  Nobody's to blame on this one.  If
you want to help out, try to ensure newbie questions get answered and
that'll help keep them in the fold.  In the meantime, maybe someone will
upgrade the docs with the current best Zope'ish ways of doing things,
including how and where to install the files in the examples.  The doc
I'm mystified by right now is my favorite, "A Technical Introduction to
Object Publishing with Zope".  This doc is great for showing that Zope
is powerful but not for telling how to install/run the examples.  I
don't know if this is one of the docs which was frustrating the poster,
but if anyone knows how to get the "guestbook2.py" example installed and
running, I'd appreciate it and bet I'd be able to figure out the rest of
the examples from that.

Cheers,

= Joe =

P.s., any docs on getting servlets running with Zope and ZServer.
Pointer(s) appreciated.