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