[ZDP] Zope Documentation wishlist

[Craig Allen]

In an earlier message I had promised to
..."try to come up with some ideas on the gaps I see,  then try to
synthesize an overall documentation architecture, then try to map the
existing and proposed pieces (and there are certainly many very
significant ones) into that roadmap."

Here's the first part, and it's completely open to comment, debate, or
whatever.  It's definitely NOT my intention to disparage in any way the existing
documentation.  Particularly for an Open Source product, Zope is quite well
documented.  But I have to assume that some of the documentation is a holdover
from when Zope's ancestors were commercial packages, being marketed (or maybe
not) to a different audience than the hordes of us now pouncing on a great
tool.  And Zope is evolving rapidly, making it hard for documentation to keep.

The main gaps from my perspective are a more extensive reference manual and what
I'll call a Programmer's Manual.

I am learning a lot from the current DTML User's Guide.  But I find that some
features that I'd like to learn more about are not documented, and what is
documented is often terse.  Missing stuff includes many methods of Zope objects,
and info like the use of structured text, which is briefly documented in the
Zope site and in the code.  Terse would include how to use attributes of the
name-space variable, where I would appreciate more real-life examples.

I'd like a Programmer's Manual that would include lots of narrative about how to
accomplish typical programming tasks using the special features of the Zope
environment.  This would include overall strategy and approach (the Zen) but
also lots of examples with explanation.

Other pieces of documentation I'd like to have would include a tutorial and a
manager's guide (in the sense of something I could give my boss to help me sell
her on Zope, not the existing Zope Manager's Guide which is a how-to for a Zope
content manager).

Readers will correctly point out that much of the material I've described in a
general way exists already, and I'd agree.  Some needs rework, maybe I'd
structure it differently, and much needs to be written.  Clearly there are folks
out there contributing frequently and enthusiastically.  

I find it easy to get obsessive about Zope.  But right now I need to go to
sleep, so I'll throw these thoughts out.  My next steps are to try to do a map
of existing material into a better articulated outline of the documents I named
above.

- Craig
-- 
Craig Allen  - Managing Partner - Mutual Alchemy
Information Architecture -- http://alchemy.nu