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).