[ZDP] Documentation Plans

[Rob Page]

Good day everyone!

As usual let me say that the idea that people are downright
mad/frustrated about Zope's docs is, in my humbly twisted opinion, a
complement to the Zope project.  I don't know about you, but there's a
lot of software whose docs I couldn't care less about.  Thanks for
caring enough to bitch about it (SERIOUSLY!!).

One of our near-term important challenges is to facilitate, encourage
and participate in creating both a Process and Toolset to harness the
documentary energy and zeal in the Zope Community.  A reality of the
situation is that by giving software away _some_ of the responsibility
for its success falls to the user community.  I believe I infer
correctly that there is consensus that Zope is a technically superior
product but that the nearly vertical learning "curve" is a REAL problem
(visions of climbing Half Dome
[http://www.yosemitevacation.com/halfdm1.jpg] come to mind)...

Digital Creations has known for some time that Zope was, um,
Documentation Challenged :^).  We have been taking internal steps to
address this.  It seems (through _numerous_ discussions on the list and
internally) that there are two distinct modes in which people USE
documentation.

People seem to either be:

(a) looking something up (e.g., syntax, method signatures, fmt tags,
etc.), or
(b) trying to learn something

Unfortunately, pre Z2 docs had a little of both mixed in and around.  As
a result, you found code snippets and examples in reference material and
vice versa.  This makes both maintenance and use MUCH, MUCH harder than
it has to be.

So Pam (Pam is the Technical Writer at Digital Creations) and I
suggested we divide our Zope docs into these two categories (i.e., (a)
and (b) above).  We've spent the last several weeks TRYING to take the
didactic material out of the reference material and the reference
material out of the didactic material.

The result is a casual naming convention...  Reference documents will
contain REFERENCE material (duh) while Guides are intended to be
didactic material.  Currently available documentation does NOT follow
this standard -- however, Z2 docs (currently in development) will.

The release schedule for these documents is:
Date:  Document
-------------------
9/15/1999:  Zope Content Managers' Reference
9/15/1999:  Zope Content Managers' Guide

9/15/1999:  DTML Users' Reference
TBD      :  DTML Users' Guide

9/15/1999:  Zope Administrator's Reference
TBD      :  Zope Administrator's Guide

TBD      :  ZSQL Methods Users' Reference
9/15/1999:  ZSQL Methods Users' Guide

One real, near-term result of this is the upcoming Zope Administrator's
Reference (ZAR).  The ZAR is an INITIAL attempt to capture, in REFERENCE
form, mostly from the System Administrator's (and ISPs) perspective,
Zope's knobs and behavior.  It should answer questions like permissions
on the var directory...  ('course that one NEVER comes up :^)

In general, it seems that Digital Creations will continue to be primary
players in the development and maintenance of _Reference_ materials.  It
is our hope and intent that the development and maintenance of didactic
materials (e.g., How-Tos, Guides, Tutorials, etc.) is a Community
function albeit with Digital Creations' active participation.  For
example, Jim Cain just posted a How-To on Apache.

We agree wholeheartedly with recent posts on both the Zope and ZDP lists
that suggest that the problem here is as much a lack of process as it is
a lack of tool/format standard.  For volunteering to tackle this in a
measured and deliberate way let me THANK Stephan Richter!  Stephan, I'll
be sending you my $0.02 worth soon...  :^)

We have some ideas about implementation...  However, before we go there,
I'd like some (any) feedback on what I've said here...  PLEASE, PLEASE,
PLEASE -- let's try and keep the discussion of documentation on the ZDP
list as opposed to the main Zope list.  It gets hard to ensure that
things don't fall through the cracks if valuable comments and ideas are
posted to multiple venues.

This is all fine and dandy to be sure.  What specifically will happen in
the near future?  Good question.  Digital Creations will bootstrap the
How-To process by developing seven (7) HowTo Documents.  These HowTos
will treat the following topics:

How-To:

o  Get Started with Zope?
o  Do interesting things with ZClasses
o  Use ZCatalog
o  Write Basic RDBMS-based applications in Zope
o  Write, use and take advantage of External Methods
o  Get Started with DTML Scripting
o  Perform the Care and Feeding of the Zope Database

These documents will be fielded using the new Zope site's How-To
capabilities and will be available in some form by 9/10/1999.  In
addition, we'll be working on the ability to index and offer a search
interface into a lot of the Zope list traffic.  Although I'm not sure
exactly what will be there, we'll have something much better than we
have now by mid- to late-September.

Thanks for your time and attention,
--Rob

--
Rob Page            Phone: +1 540 371 6909
COO                 Fax:   +1 703 995 0412
Digital Creations