OK I just noticed this thread going, and I've had many thoughts on this as I have discovered, learned, and am in the process of implementing, Zope. First of all, while it is true that Zope is a faily complex system, as you point out it shouldn't be any more complex than other major OSS projects like Apache or PHP. I am not convinced that the lack of documentation comes from the fact that it is abnormaly hard to write.

From what I've seen on zope.org, it looks to me like everything is technology driven more than needs driven. There are 5 million wiki's that lead no where for instance, and tend to come up in searches, so 90% of the time I look for something I just find various "discussions", but hardly ever anything concrete.

The Zope book exists, and I'm just starting now to get used to it now after months of Zope learning. I find the example often missing or unclear for instance ... there is NO cross referencing going on either ... No index, you just get one BIG page, you can't jump to specific sections, and so on ... Lately I find myself spending a fair amoutn of time decipehring Zope code to find the functions I want for insatnce, where they come from, whether they'r einherited, etc ... I've allways thought the LDP way of doing things is great, at least technically. I write documentation for an OSS project, and we went the LDP way of dsoing things for many reasons: first, anybody USED to working in the OSS world is familiar with such documentation, 2 it is based on DocBook, which means it is very powerfull, can be rendered in many formats, and so on. I write DocBook XML docs now, and I love it, and the users love it to. Zope is great to build sites, but it's NOT gret to make a documentation site it seems :) Using wiki's just because you can for instance, seems counter productive to me. The object oriented concept is great for programming, but not for documenting, since it "fragments" things too much I think. the ZDP it seems to me, is the way to go. The few OSS projects I've been involved in usually proceed this way, with a team of dedicated documentation writers. these are people that are familiar with the software, but also have the documentation writing required skills, proper english, page layout, content organization, etc ... In my case, the coders have it part of thei rprocess that wehn a function is added, modified, or deleted, they let the DP people know, and the docs get ammended. Of course the OOP thing makes thing different. May functions only get defined once, and re-used accross many places. This is where cross-refrencing things becomes vitallly important. you can list alll accessible functions for a given object for instance (or method, should I say), but the actually documentation of it can be done where it is defined ... A lot of docs just say "this function is available here" ... which often doesn't help much, and isn't enough information. Anyways, my .02$ :) J.F. -----Original Message----- From: Derek Simkowiak [mailto:dereks@realloc.net] Sent: Friday, March 08, 2002 4:48 PM To: Joel Burton Cc: Oliver Bleutgen; zope@zope.org Subject: Re: So what will we do? (was [Zope] What causes the community to stall so often?) This has been a very interesting thread, with many good points. Thanks to all who have posted. There were a couple of points I thought were complete rubbish. Like the idea that Zope is "more complex" than PHP, and thus can't be as well-documented. I'm sorry, but "functions" are no more easy to document than "object hierarchies". (OOP theory would state quite the opposite, in fact.) 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. It would be great if we understood why. Could it be that Zope community is just 'different'? Maybe, but I doubt it, because the Zope community overlaps with the PHP, MySQL, and Apache communities quite heavily. With the exception of the Linux Documentation Project (which has an almost unlimited scope, everything from Linux Quake install to RAID), docs are not written by the community. Having watched and participated in a few OSS projects, I've observed that almost all OSS documents are written by the people doing the coding. The PHP functions were documented by the guys who wrote those PHP functions. Note that a name on most of the Python docs is "Guido Van Russum" (who ironically enough works for Zope Corp). Most of the Apache docs were written by the core Apache developers. All of the Pango docs were written by Owen Taylor. Could it be Zope Corp's lack of prioritization? Maybe Zope Corp. management believes that "if you're busy writing docs, you're not busy developing", and so has set a mandate. Or more likely, Zope Corp just has a developer-centric company culture, and we all know how much developers like to write docs (right, Andreas? :). My personal opinion is that Zope Corp needs to realize that the community is faltering due to lack of docs, and re-prioritize. No, writing docs won't bring in cash directly. No, developers are not happy retrofitting docs for production-level code. But as somebody who stuck my neck out for Zope, and is now realizing how hard it is to find up-to-date info, I think this is a fair thing to ask of Zope Corp. Sitting on my desk right now are _The Zope Book_, _Zope Web Application Development and Content Management_, and _Zope web application construction kit_. They are mostly very good stuff, and given the present situation on Zope.org, I recommend them to anyone interested in Zope. Unfortunately, books can't keep up with issues (like Office XP and WebDAV), and the HowTos (or even mini-HowTos) just aren't getting written. Thank You, Derek Simkowiak _______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )