[ZWeb] Zope.org feedback: Documentation

Chris McDonough chrism@zope.com
05 Jun 2002 17:58:47 -0400


> I think the documentation for zope is still very poor.

It's not stellar, but it's not terrible either, IMHO.

> There is no function index nor any solid examples.

API references:

  Zope API ref http://www.zope.org/Documentation/ZopeBook/AppendixB.stx

  Python Module ref at http://www.python.org/doc/current/modindex.html

Templating references:

  DTML reference:

  http://www.zope.org/Documentation/ZopeBook/AppendixA.stx

  Page Template Reference:

  http://www.zope.org/Documentation/ZopeBook/AppendixC.stx

Solid examples:

"Examples" folder in Zopes past 2.5
Zope Book at http://www.zope.org/Documentation/ZopeBook
ZopeLabs http://www.zopelabs.com

> I suggest we all a look at http://www.php.net/manual/en/

Note that the equivalent of PHP in Zope is DTML + Python.

It would be a better comparison to compare the Zope docs + Python docs
against all PHP docs + all MySQL docs + all Apache docs.  Zope/Python
docs still might lose here, but we need specific advice on how to make
them better and help in the form of constructive specific technical
comments on existing docs.

> I know you all are going to say "it is so well documented" and "join the mailing list" or "search the mailing list archives" ...    YES I HAVE ... its time for zope to grow up.

Please provide specific advice in the form of comments against the Zope
Book and Developer's Guide about what is bad in order to help us improve
them.  You can enter these comments via the comment system that
front-ends each chapter.

- C