[Zope] Documentation survey

[John Morton]

As the tiny little text box on the survey page isn't up to long
dissertations, I'll post my comments here:

The guides need better examples and blank spots filled in, in
general. The DTML guide, in particular, needs a canonical explanation 
of the quoting rules and shortcuts so new DTML hackers understand why
you can get away with this:

<dtml-let foo=bar> ... </dtml-let>

But still need to do this:

<dtml-let foo="'constant'"> ... </dtml-let>

There is still a lot of docs using the old, ugly HTML comment style
tags, too, which is confusing, and there are a lot of examples of
using '_' and REQUEST to kludge up a temporary namespace when
<dtml-let> is the accepted means to kludge up a namespace[1].

The HOWTOs and Tips are potentially the basis of an excellent Zope
cookbook, but they require more stewardship from DC:

- They need more structure. Catagorizations like
'Authenication/Authorization', 'Using RDBMSs' and 'DTML tricks' would
save a lot of search time and provide hints towards missing
documentation. 

- The need to be vetted. There are a lot of docs with incorrect
examples and obsolete information that need to be tidied up. 

John

[1] Who the hell came up with a scoped assignment tag?! Why not
implement a <dtml-set> tag that isn't a container and that assigned to
a temporary namespace that persists for the duration of a DTML objects 
rendering. It can have a special attribute that you use to commit
changes made to an object in the temporary space back to it's
persistent name space, and you'd have a decent assignment tag.