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

[Stephan Richter]

On Tuesday 17 July 2007, Luciano Ramalho wrote:
> Everyone expects the API documentation for a framework to be highly
> visibile in it's main web site.

It now is, thanks to some people finally finishing the static apidoc.

http://apidoc.zope.org

> 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)

How does a published APIDOC version not fulfill this requirement?

> - we need to be able to collaborate with comments and examples to the docs;

I do not think that an API reference should contain comments and examples. 
That's the role of other documentation. In fact, I believe reference 
documentation should *always* be autogenerated, otherwise information-rot is 
guaranteed.

> The second point is really crucial. Just take a look at this page,
> *please*:
>
> http://www.php.net/manual/en/ref.classobj.php

A programming language is always much easier to document than a large 
framework, especially one that is dynamically configured.

> Contributing to Zope 3 docs must be made *much* easier than being a
> Zope 3 committer.

Well, you can always contribute to the Wiki, start your own page, or do 
whatever. However, just complaining about it will not improve the situation.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training