"Luciano Ramalho" <[EMAIL PROTECTED]> writes: > 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.
+1 The lask of clear google answers to a number of my initial questions was the first big hurdle when I was going through my zope 3 conversion. And +1 about the README bit too. Just $0.02 from a random community member. :) Ross > [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/archive%40mail-archive.com