On Nov 12, 2007 2:49 AM, Stephan Richter <[EMAIL PROTECTED]> wrote: > 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
Hooray!!! Thanks and congrats to all involved! > > 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? Who said it does not? My main point was that Google could not index the apidocs installed in our development boxes. Now it finally can, and that is great news! > > - 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. Information rot is a problem, granted. But do not underestimate the value of content reflecting the perspective of people who use the framework even though they are not core developers of it. > > 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. Granted, but we are not afraid of challenges! > > 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. Of course those options are always available, but they totally miss my point. My point is that, so far, the documentation of Zope 3 has been written by the framework developers for the framework developers. That is evident from the way it has been written, organized and (not) published until now. But a successful framework has many more programmers who use it than those who help develop it, and the documentation should be open to contributions from the entire community of users. > However, just complaining about it will not improve the situation. I am not just complaining. I am having a public debate with you and anyone else who cares to join about ways to make the Zope 3 API more accessible to people outside of the committers group. I see value in this, and I am happy to note that you do too, otherwise you would not have resurrected this thread which I started fours months ago. (Since then I've also started contributing to the Grok project with examples, docs and code.) Don't get me wrong, Stephan: the dynamic APIDOC tool is fantastic, you deserve many thanks from the community for it and for all of your contributions to Zope 3 over the years. Publishing the static APIDOC was a great step forward. At the same time, Grok and Plone 3 are bringing lots of new programmers to the Zope 3 world. I am sure the increased visibility and audience will be of great benefit to the Zope 3 docs, if we make it easier for people contribute. Cheers, Luciano _______________________________________________ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users