So what will we do? (was [Zope] What causes the community to stall so often?)

[Matthew T. Kromer]

Derek Simkowiak wrote:

>	
>	Compare Zope and MySQL.  Both have the same business model, both
>are popular OSS products, and both have similar target
>markets/communities.  Yet the MySQL documentation (both the User Manual
>and the developer's docs) are far more extensive than Zope's.  PHP, GTK+,
>Qt, Apache, the Linux Operating System, SGI's OpenGL, SDL, the Python
>programming language, and the Perl programming language all have
>documentation that far surpasses that of Zope.  Even smaller one-man
>projects like PyUI, or Pango, do a better job than Zope.org.
>
>	
>
Regarding Zope's documenation:

The "core" Zope documentation is actually in pretty good shape, these 
days.  The problem is, a whole lot of Zope isn't "how do I do X" where 
"X" is some simple functional/procedural thing.  Instead, its more of a 
problem of "whats the best way to do X" or "why do X vs Y?"  It's lore, 
not API.

There is an enormous amount of the Zope code base that is there because 
it evolved that way.  A lot of it becomes very optional from the API 
layer, so pure API documentation becomes misleading -- it does not 
address deeper questions of "why does it work THIS way?"

This is the biggest hurdle in Zope, in my opinion; the fact that one 
developer did things one way sort of "blazes a trail" but that trail may 
be neither intuitive, nor obvious, to another observer.  I can 
affirmatively state there are things that routinely exasperate me, 
because I want to make a little tweak to an existing example -- but I 
can't do it with a little tweak.  Instead, I end up subclassing and 
patching and coding all around, and that carries a high inertia, 
impeding my progress.

True, I can blame some of this on my fellow developers (and myself, 
too!) if I had the "this is WHY I the code is written like this" 
narrative document, I could usually pick up the how as a consequence of 
the why.  Instead, one is often left to study the plumbing to figure out 
theories of hydrodynamics.

I find that my biggest enemy in Zope is the innocuous text field.  In 
one of those many text fields in the management interface, you can type 
"anything."  Chances are good though, that only a few things will work. 
 It is frustrating when you're exposed to a "place to put something" 
when you dont know what *really* goes there, besides perhaps some 
simplitic truism from the Help System (put the foobar in the foobar slot).

Thus, I find the core of Zope to be very elegant and pleasing, but I 
find some of the contortions that need to take place to use OTHER 
people's notions on how Things Are To Be Done to be awkward and obtuse 
at times.  In many cases, one can go look at what those additional 
products do for documentation, and find that only the surface has been 
skimmed; essentially the 5% level -- you're left with no progression to 
navigate the remaining 95%.  I'm not going to name names, but I know a 
lot of my frustrations aren't unique.

Some of these frustrations aren't purely Zope, either.  I remember 
getting *very* angry at javadoc back in 1996 because I could find 
documentation on the "middle pieces" but no end pieces; I didn't want to 
replumb the graphics pipeline, I just wanted to do a few simple things, 
and no where was the arrow saying "THIS IS WHAT YOU WANT."

The corollary to this is that good programmers are trained via an 
apprenticeship -- it is vastly easier to gather knowledge by observing 
the wise than it is by starting with the Experimental Method and going 
from there.

-- 
Matt Kromer
Zope Corporation  http://www.zope.com/