[Zope] Zope Documentation

[Chris McDonough]

> The first steps to build your first Zope website often creates
enough
> momentum to hinder the newbie from learning alternative approaches
until
> much later.  How many newbies think that the DTML_Document is that
all
> powerful object because it is what is used in most examples with
> standard_html_header?  And then proceed to create a website with
100%
> DTML_Documents, only to discover they have now defeated many
benefits of
> acquisition and folders?  And then you go back and convert
everything to
> DTML_Methods with folders containing properties.

Note that this practice is explicitly denounced in the new Zope Book
edition.  As a matter of fact, I go so far as to say that people
should probably *never* use a DTML Document.  This is in the
introduction to DTML.

> When a newbie has a problem, the only choice is to search mail
list archives
> and zope.org docs.  But these are heavily laden with DTML
references and can
> quickly send the newbie into the perception that DTML is
everything in Zope,
> which just isn't the case anymore.  I think it is a big mistake
that the
> Zope Book consider p-scripts advanced.  This should be considered
a basic
> requirement for newbies.

Good point.

> We almost
> need a community endorsed comparison of DTML, p-scripts, and
external
> methods and python products and the suggested appropriate
situations for
> each.

FWIW, I try to do this in the docs (see
http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/BasicObj
ect.stx).

> How is that for trying to address both sides?
> The hard work is sitting down to create this document.

Weel, forgive me for having a one-track mind, but it's already in
motion if you're willing to live within the constraints of the Zope
Book.  I think this is its main purpose, as folks need a sanity
check when they first come in to Zope.  The ZB can help to do this
because it's highly organized, it has a controlled scope, and it has
at least a little bit of momentum (FWIW, I have spent ~ 200 hours
editing it for 2.6 and a few other people have contributed time and
effort as well).

NZO can help people *find* the Zope Book and other critical
documents, help people make decisions about which third-party
products are "good" and which are bad, and help folks better
categorized HowTos, all of which are problems that need to be solved
that are not even close to being solved by the current docset.

- C