[Zope3-dev] Re: Zope 3 needs a new documentation strategy

[Ross Patterson]

"Luciano Ramalho" <luciano at ramalho.org> 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"...