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/