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

[Chris McDonough]

> This is definately something which will greatly improve the work of 
> product authors and others. Though I have no right to demand something 
> from the people working on zope 3, it would IMO be great if zope3's 
> API-docs could be based on the source of the interfaces.

They almost certainly will be.

> Well, obviously somebody has done it, once. I gave it a try some time 
> ago, failed, and didn't have the time to persue. I did know nothing 
> about happydoc.

Ah ok.  Well, all the tools are available to whatever motivated 
individual wants to generate docs from source.

> Unfortunatly I'm still stuck mainly at zope 2.3.3 and didn't do too much 
> with newer zopes, although IIRC the API docs in HelpSys didn't change.
> I like the API reference in the Help System very much, esp. it's layout 
> is better IMO than the online version of the zope book, but both are not 
> complete (as a search for ZopeFind reveals).
> But, I use the API doc in zope for nearly 30% of my information needs, 
> 60% is reading zope's source and the rest is mailing lists etc..
> With a more or less complete API documentation this could be shifted to 
> 80%/10% I estimate. Fortunatly python source is very readable...

Hopefully being able to comment on the online version of the API docs 
will help us figure out what's missing.

Thanks!

-- 
Chris McDonough                    Zope Corporation
http://www.zope.org             http://www.zope.com
"Killing hundreds of birds with thousands of stones"