[ZWeb] Documentation
Kevin Erickson
kerickso@exempla.net
Tue, 16 Jul 2002 23:00:20 -0500
This is a multi-part message in MIME format.
------=_NextPart_000_0000_01C22D1C.8F175380
Content-Type: text/plain;
charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
I read an earlier thread about Zope documentation. The author indicated that
it was lacking. To some extent, I have to agree, and as a relative newbie to
Zope, I thought I'd offer my thoughts on documentation and web site
usefulness.
My suggestions:
Documentation in http://www.zope.org/Documentation/ZopeBook/AppendixB.stx is
good, and allowing comments is good. However, I think it would be more
valuable to organize the documentation as a web site rather than a book.
Separate links for each module would be nice, and I'd move the comments from
inline to the end. The documentation in ZopeBook itself is too littered with
inline comments that make it difficult to read. I'd rather read the document
and if I don't understand something, I'd go to the end of that section to
find user comments to help me out. This would be simlar to how the PHP
manual is organized.
I find the various add-on modules to be difficult to find. It took me quite
a while to find /Products. It seems to me that the Zope product list should
be more prominent on the site. I think one could take a lesson from
freshmeat.net on how those projects are organized and displayed. It is
difficult to determine, without actually downloading and installing a
module, whether it is what you need. I think more emphasis should be placed
on the layout and looks of the individual product pages. They are probably
under control of the individual developers, but I don't know when to take
some of the products seriously. Some don't appear to have been updated for a
couple of years, etc. I find the ones with their own home page most
appealing, like Neoboard and Squishdot. I don't have many suggestions here,
but a rating mechanism might be nice so that one can see if others have
found a product useful or not. I can also imagine a Plone portal where Zope
products have metadata that allows them to be grouped together or presented
in a "related products" menu.
In general, most add-on products (from my experience) seem to be poorly
documented. I had to buy a book to understand how to configure various
things. It wasn't that I couldn't get CMF installed, but I felt the book
went into another level of detail that made it much more useful.
More effective categorization across the entire site would be very helpful.
For example, there are 147 tips in the New User HOWTO's. If I'm looking for
something specific, it'd be nice to be able to simply drill down to it. It
would also be nice if the column sorting feature worked as advertised. It
doesn't work for me in the HOWTOs or in the various product categories.
Well, that's probably enough. I'll finish by saying Zope is one of the
coolest things I've had the opportunity to play with for a while. I have at
least 5 projects that I want to do that would have been nearly impossible
without it. Most are going to involve pitching Zope and a little internal
development against canned applications!
Kevin
------=_NextPart_000_0000_01C22D1C.8F175380
Content-Type: text/html;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META content=3D"text/html; charset=3Diso-8859-1" =
http-equiv=3DContent-Type>
<META content=3D"MSHTML 5.00.2722.2800" name=3DGENERATOR></HEAD>
<BODY>
<DIV><FONT face=3DArial size=3D2><SPAN class=3D910530003-17072002>I read =
an earlier=20
thread about Zope documentation. The author indicated that it was =
lacking. To=20
some extent, I have to agree, and as a relative newbie to Zope, I =
thought I'd=20
offer my thoughts on documentation and web site =
usefulness.</SPAN></FONT></DIV>
<DIV><FONT face=3DArial size=3D2><SPAN=20
class=3D910530003-17072002></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2><SPAN class=3D910530003-17072002>My=20
suggestions:</SPAN></FONT></DIV>
<DIV><FONT face=3DArial size=3D2><SPAN=20
class=3D910530003-17072002></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2><SPAN =
class=3D910530003-17072002>Documentation in <A=20
href=3D"http://www.zope.org/Documentation/ZopeBook/AppendixB.stx">http://=
www.zope.org/Documentation/ZopeBook/AppendixB.stx</A> is=20
good, and allowing comments is good. However, I think it would be more =
valuable=20
to organize the documentation as a web site rather than a book. Separate =
links=20
for each module would be nice, and I'd move the comments from inline to =
the end.=20
The documentation in ZopeBook itself is too littered with inline =
comments=20
that make it difficult to read. I'd rather read the document and if I =
don't=20
understand something, I'd go to the end of that section to find user =
comments to=20
help me out. This would be simlar to how the PHP manual is=20
organized.</SPAN></FONT></DIV>
<DIV><FONT face=3DArial size=3D2><SPAN=20
class=3D910530003-17072002></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2><SPAN class=3D910530003-17072002>I find =
the various=20
add-on modules to be difficult to find. It took me quite a while to find =
/Products. It seems to me that the Zope product list should be more =
prominent on=20
the site. I think one could take a lesson from freshmeat.net on how =
those=20
projects are organized and displayed. It is difficult to determine, =
without=20
actually downloading and installing a module, whether it is what you =
need. I=20
think more emphasis should be placed on the layout and looks of the =
individual=20
product pages. They are probably under control of the individual =
developers, but=20
I don't know when to take some of the products seriously. Some don't =
appear to=20
have been updated for a couple of years, etc. I find the ones with their =
own=20
home page most appealing, like Neoboard and Squishdot. I don't =
have many=20
suggestions here, but a rating mechanism might be nice so that one can =
see if=20
others have found a product useful or not. I can also imagine a Plone =
portal=20
where Zope products have metadata that allows them to be grouped =
together or=20
presented in a "related products" menu.</SPAN></FONT></DIV>
<DIV><FONT face=3DArial size=3D2><SPAN=20
class=3D910530003-17072002></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2><SPAN class=3D910530003-17072002>In =
general, most=20
add-on products (from my experience) seem to be poorly documented. I had =
to buy=20
a book to understand how to configure various things. It wasn't that I =
couldn't=20
get CMF installed, but I felt the book went into another level of detail =
that=20
made it much more useful.</SPAN></FONT></DIV>
<DIV><FONT face=3DArial size=3D2><SPAN=20
class=3D910530003-17072002></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2><SPAN class=3D910530003-17072002>More =
effective=20
categorization across the entire site would be very helpful. For =
example, there=20
are 147 tips in the New User HOWTO's. If I'm looking for something =
specific,=20
it'd be nice to be able to simply drill down to it. It would also be =
nice if the=20
column sorting feature worked as advertised. It doesn't work for me in =
the=20
HOWTOs or in the various product categories.</SPAN></FONT></DIV>
<DIV><FONT face=3DArial size=3D2><SPAN=20
class=3D910530003-17072002></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2><SPAN class=3D910530003-17072002>Well, =
that's=20
probably enough. I'll finish by saying Zope is one of the coolest things =
I've=20
had the opportunity to play with for a while. I have at least 5 projects =
that I=20
want to do that would have been nearly impossible without it. Most are =
going to=20
involve pitching Zope and a little internal development against canned=20
applications!</SPAN></FONT></DIV>
<DIV><FONT face=3DArial size=3D2><SPAN=20
class=3D910530003-17072002></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2><SPAN=20
class=3D910530003-17072002>Kevin</SPAN></FONT></DIV></BODY></HTML>
------=_NextPart_000_0000_01C22D1C.8F175380--