[ZWeb] Zope.org feedback: Zope Documentation

[alan runyan]

sorry to step in.  but i have a strong opinion on this topic.

> Before starting, could you give me a listing of the five things you like
> most about the documentation at the PHP site, along with some URLs?  It
> will be a little be apples-and-oranges, though: your needs from the PHP
> site are more advanced than your needs from the Zope site.

I would like to pipe up.   People come to ZOPE thinking its a language like
PHP.  It is not.  It uses Python.
Most people have not heard of python.  We need to make them understand this
in 2 sentences or less.
If you look at the PHP manual, it looks similiar to the Python Manual.
Because... well, they are both *languages*.

Turning to the ZOPE Book.  Which you basically have to read an entire
chapter.  because there are no further units besides chapters.  People want
to find out about metal:block.  for instance, how do they do that?  read the
entire PageTemplates chapter?

I have always wanted to see a Zope version of:
http://www.php.net/manual/en/
http://www.commandprompt.com/ppbook/
http://www.mysql.com/documentation/mysql/bychapter/

compare those layouts to:  http://www.zope.org/Documentation/ZopeBook/

I have always wanted to goto a screen and see *all the pagetemplate* tal
directives or metal directives.
this doesnt really exist.  and what does exist is lost in WikiMadness.

> We're making a big push to better organize the large amount of Zope
> documentation.  We could use some input from someone new to the site.

I dont think it takes someone new to ZOPE.  One of the reasons I do so much
w/ zopelabs is because I need a place to put things I commonly use.  It
itself has fallen into disorganization and only if you are persistent or
know how to search it (me, for instance) -- can you really go directly to
the gold.


> To answer your question, have you seen the Zope Book and Zope Developer
> Guide:
>
>    http://www.zope.org/Documentation/ZopeBook/
>    http://www.zope.org/Documentation/ZDG/
>
> Perhaps that is more information than you are looking for.

I dont think its *more* information than he is looking for.  its just the
sections are not broken up into any smaller sections.  for instance
tal/metal directives.  or all the dtml tags.  or SESSIONS.  speaking of
SESSIONs, try this:  how many clicks does it take to find out how to set/get
variables from a SESSION object?

now I urge you to goto http://www.php.net/manual/en/ and try to find
information about SESSION handling.

this I believe is a perfect experiment to find out how the typical person
*uses* documentation.

cheers,
~runyaga