-----Original Message----- From: Pierre Fortin [mailto:prfortin@earthlink.net] Sent: Tuesday, August 17, 1999 2:53 AM To: Paul Everitt Cc: 'Joe Grace'; zope@zope.org Subject: Re: [Zope] Giving up in frustration
Hi all,
I see too much potential here to give up... my critique of the docs can be summed up this way: much of what I've read so far appears to be marketing/sales oriented. I'm tired (sic) of reading how good Zope is; I came to that conclusion after reading the first overview. Every time I read a doc, if it's salesy, I start skimming ever faster. Sadly, I may be missing the answer as a result; could it be that Zope might be better documented with LESS?
I've mentioned here that I think we should have few and shallow entry points into our documentation, few meaning they aren't scattered all over the place, and shallow meaning that they are handily accessable from certain key entry points into the Zope universe (like the very first page of the default content that comes *with* Zope, and of course, www.zope.org). This jives with your 'less is more' philosophy.
but it seems to me that many "products" might be better grouped under "Tools" or somesuch if so. At one point, I wondered if I should install Zope in <somepath>/MyProject to avoid [via deletion] having the Zope docs served to the users of MyProject;
Your suggestion is sound, but the way Zope does it now is also quite sound, it's just not well Documented. The Zope Content Manager Guide does have a chapter on Roll-Your-Own Products that I've recently added some material too. It needs to be expounded on a lot to come to grips with ZClasses and advanced Product development. As another note however, creating your own Products and ZClasses is no less trivial that writing Zope 'Products' in python. Many of the high level concepts needed to write good python code are still needed to 'write' good ZClasses within your Products.
Re the "Use The Source, Luke" comments: I never had to read a single line of Python source to understand it. The docs (incl. 2 books) were quite terse in the getting started area; but script editing was the base requirement. The equivalent base requirement in Zope is akin to learning magic; the docs say so...
Ah yes, the Zen of Zope. Not magic, just some really different and powerful technology that no one else has thought of yet. Nobody really knows where the 'Zen' moniker came up but it's not a bad analogy; when you come over to Zope you have the unlearn a lot of things that other technologies have taught you. If you come from PHP or ASP, you have to learn the OO differences in Zope, such as seperating tasks from data (layout from content). If you come from Roxen, you're probably familiar with template languages (DTML is a lot like RXML), but not with the fundemental object/component nature of Zope.
Suggestion: (Sorry if this has already been proposed) don't stop development, or releases, etc. From what I can see, it should be fairly simple to create [with Zope -- doh! :-] a documentation structure and a mechanism to allow individuals to add to the docs. I still haven't found how to do it; but the current docs suggest that Versioning could also be useful here... Such a system would allow this newbie to pitch in [after finding the glass door :-].
EXACTLY. We have, at our disposal, a *Content Managment Tool*. Documentation is content. All of our 'Guides' are written in FrameMaker. This can be converted into XML and stored in our CVS in that format instead of the native FM format. These checked in files can be uploaded into Zope as XMLDocuments and traversed by a simple Guide Reader application and made fully text searchable with the Catalog. Around here he who speaks up volunteers.
Sigh... this raises the question: does versioning support check-out|-in? As in several versions working on the same elements...
Versions are not concurrent like CVS, but more like RCS. You cannot change an object locked in another version. RCS is straightforward, CVS is a beast, I suspect the same feature transition in Zope would be a similar leap of complexity.
Bottom line: a lot less "Zope can..." marketing in the docs. I'm already sold; I'm in there for *answers*.
42 ;) -Michel
On 17 Aug 1999 09:35:01 -0500, Michel Pelletier wrote:
Ah yes, the Zen of Zope. Not magic, just some really different and powerful technology that no one else has thought of yet. Nobody really knows where the 'Zen' moniker came up but it's not a bad analogy; when
It was presented by two of us at almost the exact same time when the Zope name was first announced. I don't remember who the other person was. My reference came after finishing my first Principia project (the PDMS) and had contracted Ty Sarna to help me develop a Principia/SQL-based QA tracking and reporting system. I mentioned to Ty that I considered Principia a Zen 'thing' and he applied a number of good examples of why it was so. A couple of days later, after the name 'Zope' was announced and the name games were started, I added 'Zope Zen' as a response to 'Zope Zuds'. Whomever the other person was mentioned 'Zen of Zope' within I think one posting as I received them from the maillist. The context made it pretty certain that it was derived independently :^) Ty commented that the Zen analogy was probably more correct than first appeared because not only is it hard to learn a particular methodology until one has achieved a particular 'Zen level' in Zope, it is also hard to explain that methodology to those at a lower level. FWIW, my problems with Principia and Zope have been the inconsistencies. Differences in how DTML, SQL methods, External Methods pass and accept information; in what information is available at a given 'path'; in how variable values are managed via different methods (getattr/getitem vs bobo_traverse). I have literally spent hours trying to figure out how to pass information from one place to another in Principia, usually with little or no success. Zope source has made progress possible, but Zope source is still darned hard to thread through and the error messages are often not very useful. But Zope isn't entirely the problem here. Zope makes it reasonable to bind together various products and technologies into workable applications. The 'bandwidth' of experience and background required to develop these applications is often quite a bit wider than required for standalone or standard client-server models. Examples are often crutial to comprehension, but examples often require an education in some technology that isn't necessary for the task. Another problem with questions and examples is that it is often a bit difficult to wrap a given situation into a simple set of objects. The greatest progress for me was when I decided to drop back and write some Bobo applications. Much Zope behavior became clearer in that light. Kent Polk
On 17 Aug 1999, Kent Polk wrote:
On 17 Aug 1999 09:35:01 -0500, Michel Pelletier wrote:
Ah yes, the Zen of Zope. Not magic, just some really different and powerful technology that no one else has thought of yet. Nobody really knows where the 'Zen' moniker came up but it's not a bad analogy; when
[great piece of history snipped] We need a Zen of Zope history page!
Kent Polk
Cheers, Anthony Pfrunder
participants (3)
-
Anthony Pfrunder -
kent@tiamat.goathill.org -
Michel Pelletier