[Zope] Use the source Luke -- what could be done to help documentation process? Request for comments!

[Chris McDonough]

> perhaps a dumb question, but would it be feasible to create the API-docs
> straight from the source? OFS/Propertymanager.py is a nice example of a
> doc-string. A tool like Dieter Maurer's docfinder shows how good incode
> documentation can be very valuable.

It would be.  Doug Hellmann's HappyDoc could be used.  I'm not entirely
certain that the result would be useful, because you'd need to wade through
tons of cruft to get to the "good stuff".  This is why there is interface
documentation... to separate the "private" stuff from the "public" stuff.

Interfaces, though they're manual currently and largely only used for docs
in Zope 2, play a crucial functional role in Zope 3.  This will make a huge
impact on their usefulness as documentation because they need to be kept up
to date for the system to function properly.

All this, said, if someone wanted to devise a system that allowed you to
upload a Zope release tarball (or a checkout from CVS) and run HappyDoc
against it to get HTML files and put them up for browsing, I'm sure it would
be useful to a lot of folks.

> This could perhaps be combined with a talkbacked source browsing feature
> on zope.org. Everytime I have to dive really into the source to find out
> what happens with my arguments (take ZCatalog.ZopeFindAndApply as an
> example) I wish I could have some possibility to conserve what I found
out.

Would having the API reference in BackTalk be a start towards this?

> This doesn't have to be perfect, but I *would* have added that
> information anywhere if I had known where.
> I don't know how sun creates something like
> http://java.sun.com/j2se/1.4/docs/api/index.html
> apart from the $$$$ they spend (which we/zope corp./supposedly everyone
> else here can't), but every java type I know tells me about the
> tremendous help it is. I know going that far is not doable, but it
> really show a direction for making the second half of the learning curve
> somewhat less steep.

Have you seen the API reference in the Zope Book and the Help System?  It's
maybe not as comprehensive, but this is its goal.  How can it be improved?

> I don't know if you refer to this very implementation, or to
> rating/comments in general. I can only speak for myself, but for me,
> things like that were valuable, be it freshmeat, apps.kde.com,
> www.kdelook.org. It sometimes even is valuable browsing ordered by
> score, so that I see if I might have overlooked some gems.

Yup.  A generalized ratings systems would be helpful.

- C