[Zope] FW: [Zope] _Very Long_ Giving up in frustration

[Hadar Pedhazur]

I am forwarding this with Brad's permission. It's long, but it is
instructive as well. The real point (to me) is that each new user in
Zope-land has a unique interest/need to get a particular part of Zope's
stuff going for them. In Brad's case it was updating and inserting in ZSQL
Methods. This created what I hope was a healthy discussion/admission
regarding the current state of documentation, and a variety of things that
can and should be done to correct that.

Again, I thank Brad for opening up this discussion, and for allowing me to
forward this email.

P.S. If anyone has good working examples of updating database records using
ZSQL Methods, don't be shy, they will be much appreciated (at least by one
person on this list :-).

-----Original Message-----
From: Bradford Hull [mailto:brad@tera.com]
Sent: Monday, August 16, 1999 5:40 PM
To: Hadar Pedhazur
Subject: Re: [Zope] Giving up in frustration


> Bradford wrote:
> > This is unusual, I realize, but I'm going to tell you why
> > I'm giving up on Zope now.
>
> [I'm snipping most of your post, because you say the cogent
> part above, and follow it up with a plea for better
> documentation].
>
> I am very sorry to see you go. We all understand and feel
> for your frustration. We hate to lose even a single person
> because of a stupid reason like this, but alas, it is a
> chicken and egg problem. We are building a large and complex
> system, all at our own risk. We give it away, and support
> the hell out of it, and yes, documentation lags (sometimes
> too much).

	I understand documentation lagging; you're getting great stuff
accomplished.  From my example, though, you can see that the documentation
is also necessary to succeed to the degree you deserve.

>
> However, there are a few questions that I would appreciate
> you responding to before you disappear forever. Since you
> saw the promise of Zope, perhaps you could spare a few last
> minutes to help us understand some of the problems. I'll key
> most of my questions off your next question (remember, I
> deleted an awful lot in between...).
>
> > People!  Write some getting-started documentation!  Write
> > an FAQ file!
>
> Did you find the FAQ at http://zdp.zope.org ? If not, why
> not? Was the ZDP effort too hidden?
>
	The FAQ file did not come close to the area where I was going mad
with frustration.  I wanted to be able to present data, which is covered
well and thoroughly.  I am also responsible for making methods available to
collect and maintain the data, and no hint on where to start appeared
anywhere.  ZSQL methods seemed to clearly only allow "select" statements;
when I put in an update, insert or delete, they made a big ugly mess with
error returns.  After I asked for help, a couple kind souls told me they
work anyway.  In the 2.0 beta, if I refer to one from dtml, they put up
their little generated dtml screen after mine and re-require the data I
already gave them, and then I have not been able to verify that it actually
got in the database.  Thus, I have spent 3 times as long as I have ever had
to on any other system, memorizing all available info, and can't update or
insert or delete a single row in a single-column file.
	The FAQ was not obvious enough, in my opinion, but it's sort of
slight right now anyway.  What I'd like to see is some place the basic
assumptions are answered.  When I install Zope I am installing probably 35
directories.  Then the documentation says to add Extensions to the Zope
directory.  There are a _lot_ of ways to interpret that.


> You were specifically interested in External Methods, and in
> Z SQL Methods. Do you feel that this should be covered in
> "getting-started documentation"? Can't 99% of Zope users
> safely ignore the concept of External Methods?
>
	It looks like that might be true, but in my search for any kind of
clue about how to update database fields, it looked like the only thing
that had not been ruled out, since ZSQL had so efficiently convinced me it
would only do select statements.

> Online on Zope.org, is the following:
>
> "To use an External Method, you need to place your Python
> source code file in the 'Extensions' directory in of your
> Zope directory (you may need to create this directory), or
> in an Extensions directory inside a Product directory,
> e.g. lib/python/Products/MyProduct/Extensions."
>
> You complained that you didn't know what directory the
> "Extensions" directory should be created in. You got your
> answer by asking the list. Was the documentation so far off
> that you couldn't have suggested (via the Collector, ZDP, an
> email to info@digicool.com, support@digicool.com, etc.),
> that this simple additional one-liner be added to the
> documentation?
>
> (Whoops, I see some grammatical errors in our online docs
> too...)
>
	We need more than a one liner to make up for there being no bread
crumbs anywhere for somebody to follow that wants to update their data.
You should put in a chapter in the dtml book and at least a page in the
ZSQL guide indicating the things I needed to know and could not find.  At
least, I'm assuming they're there; the help I got was credible, even if the
results were disappointing.

> > And for God's sake, don't write a patronizing letter about
> > "Does Tera have money to spend?" to a person who's trying
> > to evaluate whether something is worth spending money
> > on...
>
> You are correct. That's not the correct answer for your
> problem. However, do you begrudge us the opportunity to stay
> in business at least long enough to get the docs right? I
> hope not. Most of the answers relating to "Pay Digital to do
> it" relate to people who are looking for additional features
> in Zope. Since Zope is pretty powerful already, and we
> constantly add new stuff to the free base anyway, individual
> desires can and should be supplemented by paying customers
> (at least IMHO).
>
	I'd like to spend money supporting the company that makes something
this promising, but I have to have a case I can take to my management.  Any
client that comes with money will first have to have figured out how to do
enough to realize Zope's potential; I just saw it without being able to use
it because this whole effort is so much like things I have tried to do in
the
past.

> Today, it's Monday. As recently as Friday, you wrote:
>
> > I'll be delighted to help make documentation improvements,
> > because if it is this great, it deserves to be useable by
> > everybody.  Frankly, the documentation as it stands is
> > great marketing material, but maddening if you want to
> > insert and update data in a database, or indeed add/update
> > data at all.
>
> 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.
>
	I can only document things I can figure out; otherwise, I'd be
doggedly writing for you.  In fact, if my rant gets me enough hopeful
looking information, I'll probably install zope at home and fight through
this impasse in my spare time so I can help with this; I hate to give up on
such a good idea.  I want you to succeed, and to make money, as I said, I
just couldn't spend the time at work when I'm only hitting barriers, and
never any clear sailing.

> (giving-up-wistfully-and-will-check-back-regularly)-ly yours,
>
> I hope so. And again, if you can take a few more minutes to
> answer some of the above questions, I know that I will
> personally be grateful to you, and I suspect so will the
> rest of Digital Creations.
>
> Thanks again for taking a look at Zope.

	I'm sorry if I hurt your feelings after all the great work you've
done.  It's a thing I often end up doing: pointing out the other thing you
also have to do.  Makes me unpopular in church committees.  I suppose that
must be why I do it :-)  You folks are going to be rich if you don't die of
stress, I'm convinced - this idea is the right thing at the right time.
I'll probably be back on the bandwagon in a couple of months.  If you'll
tell me how to hook a ZSQL method for insert/update to dtml, I'll jump back
on now and start that chapter.  I'm not busy tonight...
--
Bradford K. Hull  | Do not be fanatical in your dedication to reason.
brad@tera.com     |                      Anne Rice, "Pandora"
(206)701-2066     |