[ZWeb] Zope.org feedback: Zope Documentation

alan runyan alan runyan" <runyaga@runyaga.com
Sun, 14 Apr 2002 14:54:30 -0500

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:

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.