[Zope3-dev] Zope 3 needs a new documentation strategy

[Luciano Ramalho]

On 7/18/07, Benji York <benji at zope.com> wrote:
> Luciano Ramalho wrote:
> > One of the first questions anyone needs answered when studying a new
> > framework is "Where is the canonical reference for the API?".
>
> Whatever is done, http://wiki.zope.org/zope3 is probably the right place
> for it.
>
> Wasn't someone going to get zope3.org pointed to that page?
>
> > Try googling for "zope 3 api documentation"... [1]
>
> Try googling for "zope 3 documentation".

I did also, the result is not better.

Like I said in another post (refering to the first result when googles
for "zope 3 documentation"):

On 7/18/07, Benji York <benji at zope.com> wrote:
> Does http://wiki.zope.org/zope3/Documentation help?

Not really. Before yesterday, there was no explanation about how to
access apidoc (I put that in the linked page APIDocTool yesterday).

The apidoc tool itself is limited. For debugging purposes, it might be
useful that the search is limited to registered interfaces. But while
reading about Zope 3 I wanted to check on IComponentArchitecture but
the search could not find it. I had to use grep to find it and learn
the path that I could use to browse to it in the apidoc:

http://localhost:8099/++apidoc++/Interface/zope.component.interfaces.IComponentArchitecture/index.html

And finally, the wiki Documentation page does not mention the abundant
README.txt files scattered all over the source tree where the real
documentation exists.

Cheers,

Luciano

PS. BTW, I'd like to mention that besides the people who replied in
the list, I got pvt replies of people saying that they feel the same
way as I do about the current docs.