[ZDP] DC's Zope Documentation Plan

[Amos Latteier]

Rik Hoekstra wrote:

> Two things missing as far as I'm concerned:
> 
> - A Zope 'best practices' document (when to use dtml, when python
> methods, when external methods, when ZClasses, when Python products,
> when ZClasses with Python Base classes etc etc) and how they fit
> together. I think this would be a _very_ useful document for any
> developer.

I think in general this kind of material should be covered in Guides. It
may be that the current guides do not cover this adequately. In fact, a
Developer's Guide doesn't even really exist yet.

Perhaps this kind of information would best be explained via examples,
or non-official documentation. Is the ZDP working on anything that would
align well with this need?

> - Does reorganization of the documentation also comprise a 'reading
> guide' and some system indicating the interrelatedness of pieces of
> documentation? For example the ZDP site has a Zope Snippets project.
> THis is going to be enormously useful. But the snippets have all sorts
> of uses in addition to guides and howtos. Does the Topic thing cover
> this?

Hmm. I don't quite understand the question. I think that the
interrelation between guides and references will be clear. As far as the
interrelation between how-tos and tips and the like on zope.org, I think
that Topics could be a good way to organize them.

As I also mentioned, I've been interested in an idea of contributed
example, which I think has a lot to do with the Snippets idea. My idea
was that folks could contribute examples which would be categorized and
then could be woven into guides and references. Examples could be DTML
or Python fragments with short explanations.

Thanks for your feedback!

-Amos

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