Very good point I think. The current documentation makes me feel stupid, sometimes wanting to go in some other direction than Z3.
-Torvald --- Luciano Ramalho <[EMAIL PROTECTED]> skrev: > One of the first questions anyone needs answered > when studying a new > framework is "Where is the canonical reference for > the API?". > > If you google 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, and it > takes some research > discover how to make it work. > > 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'll start 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"... > > Everyone expects the API documentation for a > framework to be highly > visibile in it's main web site. > > OK, I understand Zope 3 is undergoing a radical > reorganization right > now, which is a further push to descentralization, > making the idea of > locally generated API documentation even more > attractive. > > But I think 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. > > Contributing to Zope 3 docs must be made *much* > easier than being a > Zope 3 committer. > > Cheers, > > Luciano > _______________________________________________ > Zope3-users mailing list > [email protected] > http://mail.zope.org/mailman/listinfo/zope3-users > _______________________________________________ Zope3-users mailing list [email protected] http://mail.zope.org/mailman/listinfo/zope3-users
