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

[Luciano Ramalho]

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