[ZDP] DC's Zope Documentation Plan

[Rik Hoekstra]

> So what does this have to do with the ZDP? As the folks who have the
> best sense of what needs to be done to improve Zope documentation, I'd
> like you to review our goals and tell us if we're off base or not. What
> are we missing? 

I think the document is excellent in stating the overall goals of
documentation needs, even if they still are rather high-level. 

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

> Do we describe documentation needs correctly for
> different constituencies? 

Yes. The only question is whether there is no gap between the groups of
Zope Users and Zope Developers: it is not clear to what extent you
expect the 'users' to use dtml, python methods, external methods etc.
THese two groups comprise by far the largest group of zope users. The
old 'content managers' are users? This could be a bit clearer.

> Do we accurately describe the ZDP's role in
> the documentation process? 

Yes. It is not completely clear what the role will be, but then again
the ZDP is a rather heterogeneous group itself.

> Are the projects we're working on the right
> ones?

Yes, I think so.

Rik