-----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