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.
> 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
> The second point is really crucial. Just take a look at this page,
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.
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
Zope3-users mailing list