Vedr. [Zope3-Users] Zope 3 API documentation needs a new strategy

Torvald Bringsvor bringsvor at yahoo.com
Wed Jul 18 08:13:06 EDT 2007


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 <ramalho at gmail.com> 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
> Zope3-users at zope.org
> http://mail.zope.org/mailman/listinfo/zope3-users
> 



More information about the Zope3-users mailing list