Wed, 17 Jul 2002 02:00:22 -0400
> I read an earlier thread about Zope documentation. The author
> it was lacking. To some extent, I have to agree, and as a relative
> Zope, I thought I'd offer my thoughts on documentation and web site
Thanks for the feedback!
> My suggestions:
> Documentation in
> good, and allowing comments is good. However, I think it would be
> valuable to organize the documentation as a web site rather than a
> Separate links for each module would be nice, and I'd move the
> inline to the end. The documentation in ZopeBook itself is too
> inline comments that make it difficult to read. I'd rather read the
> and if I don't understand something, I'd go to the end of that
> find user comments to help me out. This would be simlar to how the
> 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
> a while to find /Products. It seems to me that the Zope product list
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
> difficult to determine, without actually downloading and installing
> module, whether it is what you need. I think more emphasis should be
> on the layout and looks of the individual product pages. They are
> under control of the individual developers, but I don't know when to
> 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
> but a rating mechanism might be nice so that one can see if others
> found a product useful or not. I can also imagine a Plone portal
> products have metadata that allows them to be grouped together or
> 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
> documented. I had to buy a book to understand how to configure
> things. It wasn't that I couldn't get CMF installed, but I felt the
> 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
> For example, there are 147 tips in the New User HOWTO's. If I'm
> something specific, it'd be nice to be able to simply drill down to
> would also be nice if the column sorting feature worked as
> doesn't work for me in the HOWTOs or in the various product
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
> coolest things I've had the opportunity to play with for a while. I
> least 5 projects that I want to do that would have been nearly
> without it. Most are going to involve pitching Zope and a little
> development against canned applications!
Excellent, hope it works out well for you!