This is unusual, I realize, but I'm going to tell you why I'm giving up on Zope now. I'm doing it because I think this thing has awesome potential, but if you try to make it popular with the current documentation it will sink like a rock any time a user wants to see how to input or edit data. I'm experienced, quick-witted, hard-working, dogged and persistent. I read all the available documentation until my eyes bled. I read thousands of the letters in the email forum. I could not have made a more valid effort. I finally gave in and sent the email group a plea for help, and got several kind and generous answers that answered my questions, basic, obvious questions, the kind nobody can get anywhere without having answers to. Why could I not find those answers in all that documentation digging? The answers basically led me into another blank wall one millimeter closer to my simple evaluation than I was when I started. I have learned hundreds of systems in my career, many of them quite opaque and difficult. Last week, I learned python so I could rewrite a perl script that was choking on signals from child processes, and in a day I had a solid, actually rather beautiful, threaded python application running brilliantly for me (and a great appreciation for the language). OK, learning python is not rocket science, but this is seriously non-trivial. I have never in my life experienced a system so utterly resistant to learning the basic elements you must know in order to start, as I have with Zope. I got on the Linux bandwagon when there were maybe 50,000 of us, at release 0.99 patch level 5. It was obnoxious to find the info you wanted, but not like this. People! Write some getting-started documentation! Write an FAQ file! 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... I hope you're hugely successful with Zope over time, but you'll lose a lot more like me if you don't write down the basic assumptions some place and post arrows pointing to it from everywhere. And I tell you what: If I ever have a database where I never have to put in any data, or edit any of it, I'll be back in a flash... (giving-up-wistfully-and-will-check-back-regularly)-ly yours, -- Bradford K. Hull | ... Are we having fun yet? ... Zippy the Pinhead brad@tera.com | (206)701-2066 |
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). 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? 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? 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...)
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). 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. (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.
On Mon, 16 Aug 1999, Hadar Pedhazur wrote:
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).
Hadar, I'm afraid I simply can't *afford* to sympathize with your last sentence and frankly I'm becoming very weary of seeing that sentiment put forth. As much as I may disagree with some of the ideas espoused by Richard Stallman, I wholeheartedly agree with his notion that application software lacking properly prepared documentation shouldn't be released until that defect has been fixed. Period. I doubt that the documentation writer DC has hired will ever catch up in the current climate. I doubt that DC will ever achieve its goals until that problem is addressed. If I were running DC, I'd declare the following policy, effective immediately: """The current feature freeze on 2.0 will now be supplemented by a development freeze. All developers, salespeople, in fact anyone with a brain and a pair of eyes and hands, will reassign themselves to supporting the documentation effort until that effort has come abreast of the current and near-term development. Henceforth, we will *not* release until documentation is in hand."""
On Mon, 16 Aug 1999, Hadar Pedhazur wrote:
We give it away, and support the hell out of it, and yes, documentation lags (sometimes too much).
Patrick Responded:
I'm afraid I simply can't *afford* to sympathize with your last sentence and frankly I'm becoming very weary of seeing that sentiment put forth.
I understand that completely. I'll respond more fully below.
As much as I may disagree with some of the ideas espoused by Richard Stallman, I wholeheartedly agree with his notion that application software lacking properly prepared documentation shouldn't be released until that defect has been fixed. Period.
Well, then there won't be too much free stuff of serious value given away. We're yet to see a company like Digital Creations make serious money over a long period of time. We're pioneering a space, and paying dearly for the priviledge. We're glad to do it, but exactly how would all of the current "Powered by Zope" sites, testimonials, case studies, etc., be accomplished if there was no software, while it awaited the documentation?
I doubt that the documentation writer DC has hired will ever catch up in the current climate.
You're correct. It was my hope that the ZDP effort would help to ameliorate that problem. I, for one, think they've made a very admirable dent. I also think that the list, while a difficult thing to search, is an invaluable resource to the hardy. To me, the problem with the docs were not a complete lack of documentation, but rather a lack of organization. Unfortunately, that allowed us to cede such an important effort to a vigorous group of volunteers. I say "unfortunately", because since then, 2.0 introduced so many new concepts, that clearly reorganizing the old docs alone, would not give us the clarity that we would need.
I doubt that DC will ever achieve its goals until that problem is addressed. If I were running DC, I'd declare the following policy, effective immediately:
"""The current feature freeze on 2.0 will now be supplemented by a development freeze. All developers, salespeople, in fact anyone with a brain and a pair of eyes and hands, will reassign themselves to supporting the documentation effort until that effort has come abreast of the current and near-term development. Henceforth, we will *not* release until documentation is in hand."""
That may be a very realistic thing for us to do, seriously. However, 2.0 is still not out, and it would have been wrong (IMHO) to hold off the release that brings so many new things (ZClasses, multi-threading, ZCatalog, etc.) until they were all documented. I realize that the effort on some people seems interminable. For that I am sorry. Sorry not only for them, but for us, for having lost an opportunity for another evangelist. However, for each of those, there are many people who are doing amazing things with Zope, witness Squishdot, Phillip Eby's DTML tags, and many more that I should pay homage to here... If we had waited for the docs to be updated, they'd only be starting their efforts at some undetermined point in the future, and the Zope world would be a sadder place for that. Please don't misunderstand this response. I think it's a critical problem. However, I also think that the state of the current docs, bad as they may be, are surmountable, and have been surmounted by many people. After all, you do have the source. I know that this isn't a mass market answer, but Bradford himself gave an excellent example of how easy it was to master Python, so those that want the power of Zope sooner, should avail themselves of this (last-ditch) avenue.
Hadar Pedhazur wrote:
I doubt that the documentation writer DC has hired will ever catch up in the current climate.
You're correct. It was my hope that the ZDP effort would help to ameliorate that problem. I, for one, think they've made a very admirable dent. [snip] To me, the problem with the docs were not a complete lack of documentation, but rather a lack of organization. Unfortunately, that allowed us to cede such an important effort to a vigorous group of volunteers. I say "unfortunately", because since then, 2.0 introduced so many new concepts, that clearly reorganizing the old docs alone, would not give us the clarity that we would need.
Thanks; unfortunately the ZDP effort also currently is in stasis. This is because we all tend to prefer developing with Zope instead of writing documentation, we're trying to learn ourselves, and we're volunteers anyway. The ZDP needs someone to push things forward. In the past, that was me, I think -- but I lack the time right now, I'm afraid. Working in the ZDP can however be rewarding; documenting something may be difficult if you don't know about it yet, but it's also an excellent way to learn more about it. Also it's just nice to see the docs grow, and to have them, of course. Part of the problem (for me) is that things are currently too difficult. We lack a good FAQ tool, for instance. Me editing text files didn't really work well -- I became a bottleneck, and I gave up. We have ZTables to implement a FAQ tool, but the ZDP site runs on Zope 1, and we're all busy with Zope 2 right now. And the Portal Toolkit is coming, which may offer better features still, etc. We got into a deadlock there, I think. Anyway, if it were easier for me and others to add FAQs and so on, I think I'd put more time in it. The Zope Portal Toolkit seems to be a step in the right direction with the way it allows you to add HOWTOs. I've also seen too little communication with the person responsible for docs at Digital Creations; the ZDP doesn't seem to have heard much (I did send an email). Some organization talent and simply grunt editing of community provided docs would be very helpful to the ZDP, I think. In general, the community is perfectly capable of turning out lots of unpolished documentation (we haven't seen anything near the full potential of that yet), but not so capable of editing and organizing these. I like writing and editing docs myself, but organizing them coherently I don't like doing so much, especially if I need to do it by hand. Anyway, Hadar, I agree with your analysis. I was just trying to describe my set of diffuse feelings from the ZDP point of view. I've felt vaguely guilty for not doing more about the ZDP. All this criticism aside, I do think Digital Creations in general is doing an excellent job, both community wise (you people are helpful and friendly in general -- I didn't percieve as much nastiness in this thread as others saw, apparently :), and in the way you people come out with the most amazingly nice stuff that we all can really drool over. This rapid development, though sometimes bad for documentation, is also very impressive and very attractive at the same time. Don't stop that; it's fun! (though some stabilization is of course desirable after the mad rollercoaster ride towards Zope 2 -- but development can go quite quickly on products that _build_ on Zope 2). Just organize the documentation effort better. Our biggest need, I think, is an organization of the documentation infrastructure. Someone needs to be get pretty radical there -- ripping apart everything and putting it all together again in a better way. I'll definitely be around to give my help. Regards, Martijn
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.
Joe wrote:
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).
I am truly sorry you read this in that way. One of the most wonderful things about the Zope community has been the very healthy tone and discussion level on the mailing lists. They have only once degenerated long ago, and when people refused to get sucked into the bait, the thread died. I was _serious_! On Friday, Bradford wrote an excellent post, and offered to join in the effort. I didn't ask him to document something he didn't understand out of the clear blue. I simply wondered what happened over the weekend to take unbridled enthusiasm for Zope (read the beginning of his post on Friday!), and turn it into utter despair. Upon re-reading it, I can, of course, see your point. That wasn't mine though...
I missed the complete context and misinterpreted your intent from the message. Hadar, please accept my apology. I believe the zope community is astoundingly good at answering questions intelligently, just bunches of questions can go unanswered and there doesn't seem to be a faq good enough to eliminate the need for basic questions. Perhaps if we can translate some of the expounded list knowledge into faq material, zope startup will be all that much easier. Cheers, = Joe = Hadar Pedhazur wrote:
Joe wrote:
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).
I am truly sorry you read this in that way. One of the most wonderful things about the Zope community has been the very healthy tone and discussion level on the mailing lists. They have only once degenerated long ago, and when people refused to get sucked into the bait, the thread died.
I was _serious_! On Friday, Bradford wrote an excellent post, and offered to join in the effort. I didn't ask him to document something he didn't understand out of the clear blue. I simply wondered what happened over the weekend to take unbridled enthusiasm for Zope (read the beginning of his post on Friday!), and turn it into utter despair.
Upon re-reading it, I can, of course, see your point. That wasn't mine though...
In article <199908161852.LAA09903@gershwin.tera.com>, Bradford Hull <brad@tera.com> writes I'm not giving up, but I second this plea. The learning curve is steep and without some real docs on Zope it is hard. What's worse is that there are (at least for guys like me) at least two learning curves. One is all the usual new stuff inside active servers and second is the alien ExtensionClass/Acquisition things which modify everything I struggle to learn about in python. A more minor thing is having to modify all my notions about Web pages etc. I don't have a good handle on the syntax and you've slipped through another language and now with all the XML stuff we're about to get a third wave.
This is unusual, I realize, but I'm going to tell you why I'm giving up on Zope now. I'm doing it because I think this thing has awesome potential, but if you try to make it popular with the current documentation it will sink like a rock any time a user wants to see how to input or edit data.
I'm experienced, quick-witted, hard-working, dogged and persistent. I read all the available documentation until my eyes bled. I read thousands of the letters in the email forum. I could not have made a more valid effort. I finally gave in and sent the email group a plea for help, and got several kind and generous answers that answered my questions, basic, obvious questions, the kind nobody can get anywhere without having answers to.
Why could I not find those answers in all that documentation digging?
The answers basically led me into another blank wall one millimeter closer to my simple evaluation than I was when I started.
I have learned hundreds of systems in my career, many of them quite opaque and difficult. Last week, I learned python so I could rewrite a perl script that was choking on signals from child processes, and in a day I had a solid, actually rather beautiful, threaded python application running brilliantly for me (and a great appreciation for the language). OK, learning python is not rocket science, but this is seriously non-trivial.
I have never in my life experienced a system so utterly resistant to learning the basic elements you must know in order to start, as I have with Zope. I got on the Linux bandwagon when there were maybe 50,000 of us, at release 0.99 patch level 5. It was obnoxious to find the info you wanted, but not like this.
People! Write some getting-started documentation! Write an FAQ file!
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...
I hope you're hugely successful with Zope over time, but you'll lose a lot more like me if you don't write down the basic assumptions some place and post arrows pointing to it from everywhere. And I tell you what: If I ever have a database where I never have to put in any data, or edit any of it, I'll be back in a flash...
(giving-up-wistfully-and-will-check-back-regularly)-ly yours,
-- Robin Becker
Um, I believe that the upcoming ZPT site has HOWTO's and FAQ products in it. It will (I hope) also have a Debian style package browser. Maybe the ZDP people can get in touch with Amos about getting access to it. Cheers, Anthony Pfrunder PS: Does anyone know if it is up again? I promise I'll keep my doc's up to date this time ;)
participants (7)
-
Anthony Pfrunder -
Bradford Hull -
Hadar Pedhazur -
Joe Grace -
Martijn Faassen -
Patrick Phalen -
Robin Becker