This I find is a VERY!!! good proposal. How would I have loved to have such a thing!! (and still do) Robert ----- Original Message ----- From: "Oliver Bleutgen" <myzope@gmx.net> To: <zope@zope.org> Sent: Monday, October 22, 2001 1:14 PM Subject: RE: [Zope] A new list needed (and/or a new feature of documentation)?
Being a non-so-developer type myself and not being too good with python yet, I had said the same thing myself. But truth is, its all there in some place or another. Finding it is the difficult part because the really technical information lies in documents with slightly ambiguous names. Who would thing that AppendixB.dtml was going to teach me how to resize an image using <dtml-var "ImageObject.tag(width=yadda)">?
But something I think may be nice, but perhaps is already here. Is there a Code Collector that we can read/submit submissions of coding (dtml and python)? I stumbled upon a site somewhere that had something like it and then I lost the link. However, it only had 3 entries at the time.
There is one at zdp.zope.org (code snippets). I know I repeat a mail I did sometime before, but
zdp doesn't work.
It doesn't work because we split resources and make it too hard for people to contribute. I want to propose another idea, which is IMO well-tested and works good.
Php.net has it and postgresql.org too. Php.net calls it annotated documentation. It gives users the ability to post remarks to chapters of the documentation, for adding errata, catches, and code snippets. I don't know why nobody seems to think this is worthy, IMO it would help to build a more or less _single_ source of information esp. for "newbies" (but not only). How often do we read "I tried xyz from chapterNN of blabla-documentation and it doesn't work", and the answer is "You got it nearly right but you also have to do ZvoodooStuff".
Take for instance http://www.php.net/manual/en/features.file-upload.php There are many posts describing what they tried, what didn't work, and what they did to remedy the problem - exactly what is IMO needed for zope. This is the place where (most) beginners (and others) will look first - attached at the relevant chapter of the documentation. This is the place where people can easily contribute after solving their problem, after all they went there before in search for help. And finally, it's the place where authors of the docs have a central repository for feedback, to see what they might add in the next rev of the documentation.
For those of us that struggle at first with Zope syntax and language, code snippets are the very best thing to learn from. Its frustrating to know how something is done, but have to ask a question on the list that verifies you missed something simple because the answer was as stupid as the question, once its worked out.
Btw. sometimes I have problems with not zope-, but browser-/http- specific questions. A search on google often yields a link to phps annotated docs, and all I have to do is to translate that solution into zope. Why can't we have something like that? I think the building blocks are there already.
cheers, oliver
_______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )