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 |