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

[Paul Carduner]

+1

The problem is that the people who know where to find all the
information are too busy producing very successful Zope3 applications
:).  I mean, making the hard to find documentation more available
could be considered helping the competition?  At some point, someone
(I believe Stephan Richter) tried writing a static apidoc generation
script.  After a quick search I determined that "The script was never
completely finished, polished and stabilized."

I have found the various README files to be incredibly informative.
That is the first thing I tell people to look at when they ask me
about zope documentation.  apidoc is really a minimalist reference for
just checking on zcml attributes, etc. and occasionaly looking at the
"books".

I would be interested in seeing someone write a Grok application that
hooks directly into the README files in the svn repository, allowing
for annotations/comments on the READMEs.  If the README files became
more public, maybe the authors would improve them.  Also the irony of
writing a zope api documentation tool in Grok is quite appealing to
me.

- Paul


On 7/17/07, Luciano Ramalho <luciano at ramalho.org> wrote:
> 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.
>
> Cheers,
>
> Luciano
>
>
> [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 at zope.org
> Unsub: http://mail.zope.org/mailman/options/zope3-dev/paulcarduner%40gmail.com
>
>