[Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation

Craig Allen cba@mediaone.net
Mon, 29 May 2000 11:16:38 -0400


I must apologize in advance, I have not read the entire thread, but
here's my answer to your question:
> So what do you folks think?

My advice: be a benevolent despot.  

I started to get involved with ZDP many months ago, and proposed a
structure for documentation, created a folder hierarchy to support the
proposed framework (some of which was still evident on the ZDP site for
a long time), and generally got zero feedback or support.  My perception
of the problem was that no one was in charge, no one could say yeah or
nay, and no one said "This looks like a good direction for now, let's
pursue it".  Not that I necessarily thought that my work was the
ultimate answer, but no one else was either proposing an alternative or
suggesting needed modification.  Instead, other folks just did their own
thing.

Now it looks like individuals get energized, produce a body of work
(e.g. ZBook, ZQR) and then get burned out.  My suggestions are, in
decreasing preference:
 - consult with experts in learning/documentation design to come up with
a framework for documentation; and/or,
 - find a site, product, book, or documentation set for a comparable
product, and copy ideas from it; and/or,
 - work with ZDP activists and the mailing lists to come up with a
framework, identify materials and formats to fit the framework, identify
gaps, and then start assembling the structure.  This is my least
preferred path just because I'm skeptical that a group effort will move
fast enough.  I recognize that this is counter to Open Source practice,
but I really believe inadequate documentation is the main barrier
between Zope and world domination!

And good luck!  Zope remains a great tool with an excellent user/support
base, let's make it better.

Craig