[Zope] general API question

[Paul Winkler]

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