[Zope] Re: What causes the community to stall so often?

[Adam Fields]

Mitch Pirtle says:
> > 2) What is the secret to PHP's excellent documentation?
> 
> My suspicion is that their job is made easy by everything being wrapped
> up in a function.  That may or may not be the way they intended it, but
> just the function reference alone is all I need for a very healthy and
> productive PHP life.  I can do a tremendous amount of kewl things just
> knowing about those functions.

The function reference is pretty good, but there's still a fair amount
that's undocumented or not well documented, or simply poorly
cross-referenced. But... it's still pretty good.

> So, how to mirror that in the Zope world?  We simply cannot.  There are
> a heckuva lot more than just functions here - there's objects, methods,
> DTML, ZPT, CMF, and all that other stuff I haven't learned about yet.=20
> I'm still hazy on DTML, and moving to ZPT/CMF because of both the 2.5
> release and an inferiority complex.  So I am sure I am missing
> something.
[...]
> Is there a better way to document all these lumpy, bumpy aspects of the
> Z Object Publishing Environment?

I've written a review article, in which I cover some of my impressions
about this:

http://www.cmswatch.com/Features/ProductWatch/FeaturedProduct/?feature_id=61

I think that a lot of the problems with the documentation are with the
organization of the documentation, not with the content. The people
who write documentation related to Zope tend to write it for
themselves, from the perspective of someone who already knows how to
do the thing they're describing. It's difficult to put yourself in the
shoes of someone who doesn't know why a thing works the way it does,
and write without assumptions. It's okay to not document everything
all in one place - this is what hyperlinks were invented for.

Two very important things missing, from my perspective, are 1) a
strong central repository (with permanent urls), so people know where
to go for answers instead of searching with Google, and b) having
people who write documentation have some knowledge of what else is out
there so they can link to it and comment on it (which would be easier
to do if there was a strong central repository).