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

[Doyon, Jean-Francois]

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 )