On Thu, Sep 30, 2004 at 09:22:47PM +0200, Dieter Maurer wrote: (snip)
I already argued with one of the first authors of the Zope Book and the online help content (Michael). I could not convince him. But the current state of affairs (outdated, incomplete, week online help) demonstrates that I was right...
Well, there is one good reason for the BackTalk version of the API reference - namely, the backtalk feature. Users sometimes have good questions that deserve to be addressed, and as an occasional Zope Book editor, I've found BackTalk an excellent way to gather these. (As a Zope Book *reader*, I find them mostly annoyances... don't know how to reconcile these two issues.)
Yes. I don't know if you've seen my long-term proposal: http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference
I did not read the proposal but followed the occurrences in the mailing list.
Personally, I would go this route and would not try to complete the API reference in the Zope Book.
This does not mean, that no work whatsoever should go into the API reference: if something *really* important is missing, it should be added. But, there are more important tasks than making it 100 per cent complete...
Agreed. I'm not aiming for 100. But I'm aiming for significant improvement over the current one which has become really bad IMO.
In that shiny sci-fi world, DocFinder would still be a great way to explore the *implementation*, but we would also have clear browsable documentation of the *interfaces*. But this is an even bigger job than twiddling the current API reference by hand...
Are you sure?
Well, no. But it requires adding a whole lot of files to the Zope source code since many things do'nt have interfaces, and touching the classes to assert that they implement those interfaces, and adding tests that validate that they implement those interfaces. To me that sounds like a big job and probably the results will not be seen by anyone until zope 2.9. Compare this to the revision of the online API reference, which in my estimate is about half finished and can already be read by people today at plope.com.
That's what I like to call the power of handling person. Were I the handling person, I surely would proceed the other way round :-)
:) Thanks for the input. -- Paul Winkler http://www.slinkp.com