[Zope] RE: Documentation survey

[Amos Latteier]

John Morton wrote:
> 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>

I agree. The guides need to be complete, error free, and chock full of
examples.

> 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].

Hmm. I wasn't aware of the old style syntax, that should definitely be
updated. I also agree that we need to review guides and update examples
to use the latest and simplest techniques. This is especially true for
DTML.

> The HOWTOs and Tips are potentially the basis of an excellent Zope
> cookbook, but they require more stewardship from DC:
> 
> - They need more structure. Categorizations like
> 'Authenication/Authorization', 'Using RDBMSs' and 'DTML tricks' would
> save a lot of search time and provide hints towards missing
> documentation. 

I agree. We do have categories for How-Tos but they are not currently
sorted on Zope.org by category. Probably the categories could be
improved, too.

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

Again I agree. How-Tos should also provide some feedback system to allow
readers to comment on How-To and point out problems.

Thanks for your excellent ideas!

-Amos

--
Amos Latteier         mailto:amos@digicool.com
Digital Creations     http://www.digicool.com