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

[Oliver Bleutgen]

Hi all,

Chris McDonough wrote:
>> So in the next version of the printed book there would be a cd packed 
>> with code-examples ,-)
> 
> 
> I'm not sure if you've seen it, but the newest Zopes ship with an 
> Examples folder that contains some simple example applications.  They're 
> not "real world" apps because they're very simple, but they should get 
> folks "up and going".  Maybe there needs to be a Zope Book chapter that 
> explains the examples in the Examples folder.
> 
>> What is the status of Zope Help-files - and what is going to happen 
>> with them?
> 
> 
> They continue to be updated every release.  The help system 
> implementation might change, but the content will stay the same (or 
> hopefully be improved).  Currently the API reference in the Zope Book is 
> generated right from the help files, but it may make sense to make a 
> different book (API reference or something) out of it to give it more 
> exposure.

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.
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.
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.

>
>> Yes. I remember some time seen some proposition about rating system 
>> for zope.org products. That would be nice, since peers would be able 
>> to rate and comment on products. Also the feature to send comments to 
>> the maker -- and also on the product page, would be nice. Meaning that 
>> if there is a product which looks in words good, but in reality is 
>> buggy crap, and the writer is long gone.. for example changed company 
>> and email address etc.. users could write comments about their luck 
>> with product / howto - etc.
> 
> 
> Yes, parts of this exist in new.zope.org.  I'm not sure that helps a 
> lot, though. ;-)

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.

cheers,
oliver