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 _______________________________________________ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
