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