New subject: [Zope] A new list needed (and/or a new feature of documentation)?

22 Oct 2001

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

RE: [Zope] A new list needed (and/or a new feature of documentation)?

Oliver Bleutgen

Robert Rottermann

Joel Burton

tags

participants (3)