[Zope] Documentation Solution

[Eron Lloyd]

As a member of the ZDP, as well as several other Documentation Projects,
I understand exactly where these complaints are coming from. I'm still
in the learning stage of Zope, and I admit, am stumbling over the
current *official* documentation; nonetheless, I think I'm gaining a
foothold. I'm not going to say what Digital Creations should do about
this dilemma, but present several options:

1. Create a good communication with the ZDP. As far as I know, not much
if any of the ZDP's effort has made it into official documentation.
Let's encourage eachother, not point fingers. Let writers know that they
are needed; even better, compile a list of EXACTLY what needs to be
written/updated.

2. Have volunteers mine the mail archives and compile notes. There is
TONS of excellent questions/answers to real world situations on
everything Zope. Let's start going through and indexing them.

3. Put together TUTORIALS. If you know how to do something, document it.
I'm sure someone would appreciate it. Contact the ZDP, and we'll put up
a good collection.

4. Proofread. Many of the Official Guides have typos and broken code
examples. Let Pam know. A simple page# description would help ALOT.

5. NEWBIES: Instead of just requesting help on something, request
someone to make a How-to. This is another way we can gather priceless
material instead of letting it dissolve into the mail archives.

6. A Hypertext help-system integrated into the Zope installation.

7. What tools? Here are some tools we could decide to use for docs
(+/-):

- DocBook SGML/XML DTD: Powerful, standardized; yet complex - VERY
complex.
- StarOffice: good Word Processor, supports multi-user docs (redlining,
etc.), free; Big, some say bloated.
- Structured Text: native to Zope, easy to write in; not functional
enough, can't convert to different formats easily
- CONGLOMERATE: This could be our answer - an XML-based Document
editing/management system, FREE (GPL'd); not yet completed...
(www.conglomerate.org)

I thing Conglomerate could be our solution. But for now, let's bump
heads and work together, and put reality back into check.

Eron Lloyd