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

[Luciano Ramalho]

On Nov 12, 2007 2:49 AM, Stephan Richter <srichter at cosmos.phy.tufts.edu> 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