[ZWeb] Documentation

[Chris McDonough]

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

Thanks for the feedback!

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

You may turn the comments off using the "COM OFF" button at the top of
any of the pages of the Zope Book.

I agree that the API reference should be presented better, and perhaps
should not be inline-commentable.

> 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

FWIW, I'm editing the Zope Book at the moment for 2.6 and I make
frequent references to /Products.

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

Yeah.  We know. Got a few extra days to help us?  ;-) See
http://new.zope.org:15080/ZopeOrg for progress.

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

Yup.  CMF in particular badly needs better docs.  That said, it's good
that you could go out and buy a book to help out.  That didn't use to
be the case 2 years ago. ;-)

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

Yup.  This is also in the domain of "new zope org".

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

Excellent, hope it works out well for you!