[Zope] Giving up in frustration

[Michel Pelletier]

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