[ZDP] BackTalk to Document The Zope Book (2.6 Edition)/Appendix B: API Reference

[webmaster at zope.org]

A comment to the paragraph below was recently added via http://zope.org/Documentation/Books/ZopeBook/2_6Edition/AppendixB.stx#1-0

---------------

  This reference describes the interfaces to the most common set of
  basic Zope objects.  This reference is useful while writing DTML,
  Perl, and Python scripts that create and manipulate Zope objects.

    % Anonymous User - June 20, 2002 6:55 pm:
     This section needs a Table of Contents too.

    % Anonymous User - June 26, 2002 1:43 pm:
     The reference describes nearly nothing when you don't know the solution! 
     Examples are absolutely necessary.

    % Anonymous User - July 12, 2002 3:32 pm:
     i agree.

    % Anonymous User - July 14, 2002 5:21 am:
     Strongly disagree.  This is a reference, not a tutorial or explanatory text.

    % Anonymous User - Aug. 20, 2002 11:13 pm:
     A reference doesn't contain explanatory text?

    % Anonymous User - Nov. 12, 2003 10:52 am:
     Look at http://www.php.net : it's both a precise API reference for PHP developers, and a tutorial full of
     interesting samples.
     Apart from the Zope Book (which efficiently sums up the ZMI) I have rarely seen such a poor pedagogical and
     practical approach as among the zope documentation.

    % Anonymous User - Nov. 12, 2003 8:18 pm:
     As a Zope User, imaging my surprise to see this page referenced in the W3C Validator service's tip of the day
     for further information on how to implement a page redirect instead of a page refresh (see
     http://www.w3.org/QA/Tips/reback ). What a kudo from the industry! Imagine my disappointment at landing on
     this mess of bickering commentary as well as no discussion or TOC for finding syntax for redirection. I think
     a lot of people following the link and unaware of Zope would click 'back' pretty quickly with a lees than
     positive impression. FWIW, Duke

    % Anonymous User - Dec. 11, 2003 12:43 am:
     I agree with the comments suggesting that a table of contents (and an index too perhaps) would enhance the
     value of this API reference. I also agree that some code snippets showing proper usage and some explanatory
     notes would help to make this API reference more useful.
     I come from a Java background.

    % Anonymous User - Dec. 24, 2003 1:55 am:
     So convoluted! So frustrating! It would be much more useful to have this information organized in a more
     hierarchical fashion, like Python's Global Module Index (c.f.
     http://www.python.org/doc/current/modindex.html)

    % Anonymous User - Jan. 18, 2004 5:46 am:
     For the love of god, someone please listen to these suggestions.

     1) Table of contents / index
     2) General organization (php.net, http://www.python.org/doc/current/modindex.html) 
     3) Example code.

     One of greatest things that the PHP community has going for it is a clear, concise, organized reference, WITH
     EXAMPLES. Newbies get rolling instantly, and advanced users are able to skip to exactly what they're looking
     for.

    % edcass - Jan. 18, 2004 7:24 pm:
     man, I stopped developing in Zope 2 years ago... I thought this would have been dealt with by now. Well, I
     suppose I'll finish this project off and then check back in in another 2 years. See you then...

    % edcass - Jan. 18, 2004 7:24 pm:
     man, I stopped developing in Zope 2 years ago... I thought this would have been dealt with by now. Well, I
     suppose I'll finish this project off and then check back in in another 2 years. See you then...