+1 The problem is that the people who know where to find all the information are too busy producing very successful Zope3 applications :). I mean, making the hard to find documentation more available could be considered helping the competition? At some point, someone (I believe Stephan Richter) tried writing a static apidoc generation script. After a quick search I determined that "The script was never completely finished, polished and stabilized."
I have found the various README files to be incredibly informative. That is the first thing I tell people to look at when they ask me about zope documentation. apidoc is really a minimalist reference for just checking on zcml attributes, etc. and occasionaly looking at the "books". I would be interested in seeing someone write a Grok application that hooks directly into the README files in the svn repository, allowing for annotations/comments on the READMEs. If the README files became more public, maybe the authors would improve them. Also the irony of writing a zope api documentation tool in Grok is quite appealing to me. - Paul On 7/17/07, Luciano Ramalho <[EMAIL PROTECTED]> wrote:
One of the first questions anyone needs answered when studying a new framework is "Where is the canonical reference for the API?". Try googling for "zope 3 api documentation"... [1] Everyone coming to a new framework expects the API documentation for it to be highly visible in it's main web site, or at least available somewhere on the Web... OK, I understand Zope 3 is undergoing a radical reorganization right now, which is a further push to decentralization, making the idea of locally generated API documentation even more attractive. But we also need the API published on Zope.org, for a few advantages that the apidoc tool will never be able to give us: - we need to be able to use Google to search the API documentation (even if the apidoc search worked perfectly, which it doesn't) - we need to be able to collaborate with comments and examples to the docs; The second point is really crucial. Just take a look at this page, *please*: http://www.php.net/manual/en/ref.classobj.php Last year I had to do a project in PHP, and again and again the answers I was looking for were in the contributed comments and examples, even though their documentation is very compreehensive. The same amazing user participation can be seen in all 23 languages (!) in which the PHP API is documented. And finally, we should also publish the invaluable README.txt files scattered in the Zope 3 package tree, as they are not visible through apidoc at all, and initially I just thought they contained installation instructions so I ignored them. Zope 3 documentation must be made more visible, and contributing to to it should be *much* easier than being a Zope 3 committer. Cheers, Luciano [1] Googling for the docs: what I found Earlier today I googled for "zope 3 api documentation". The first link is Stephan Richter's mail of Jan/2004 announcing API doc. In it, there is the link: http://localhost:8080/++apidoc++ However, that URL is not active by default. The second link returned by Google is this: http://wiki.zope.org/zope3/Documentation Here we find vague references to a certain API Doc Tool, but no explanation of how to enable it and access it (OK, that is a Wiki, so it's easy to fix; I just started the APIDocTool page). The remaining links returned by Google are even less helpful, and on page 2 we get a link to Shane Hathaway's post titled "Zope 3 Frustration"... _______________________________________________ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/paulcarduner%40gmail.com
_______________________________________________ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
