[ZDP] Documentation Plans

[Martijn Faassen]

Rob Page wrote:
> Good day everyone!

Good evening to you! :)

> 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!!).

Thank you for taking our bitching in such a friendly and productive way. :)

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

Great; a little guidance from Digital Creations here can go a long way, I
think. Take for instance the HOWTO product in the Zope Portal Toolkit; only
a few days after it's announced we have quite a few HOWTO's in the making.

> A reality of the
> situation is that by giving software away _some_ of the responsibility
> for its success falls to the user community.  

Agreed completely. That's why we're here. :)

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

Zope uses some revolutionary concepts; that makes Zope technically superior
and harder to learn about. Though it's not that hard to get started
productively with Zope, actually. But taking it a bit further takes too much
persistence right now.

> 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

Although one can learn from a reference. And one can look up a recipe in a
HOWTO. I agree with the basic analysis, but plenty of indices and
cross-references are helpful here, from the reference to the guides, and
vice versa.

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

Yes. Good analysis.

[snip reference vs guide distinction; Pam and Rob's heroic attempts to split
current documentation :), exciting new and redone docs coming 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.

Yes, that's a good split. Though of course the community is interested in
helping with reference docs as well. Also there's the FAQ; a FAQ can be used
as a reference, but at the same time is an example of documentation that can
be produced by the community very well. Perhaps the FAQ can become a kind of
gateway into further Zope documentation (references, guides, HOWTOs,
tutorials, examples), and also at times a quick summary of things. An active
FAQ is the kind of thing that can respond to changing documentation demands
the most quickly.

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

I agree back. :)

> 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...  :^)

I'm thanking Stephan too! Stephan has been very good at getting the process
started again. I'll be assisting Stephan. :)

> We have some ideas about implementation...  However, before we go there,
> I'd like some (any) feedback on what I've said here...

Okay. :)

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

Yes. One of my main functions is to guide people to the ZDP list. :)

[more exciting documentation developments; HOWTOs]

> Thanks for your time and attention,

Thank you, Rob, Pam, and Digicool in general!

Regards,

Martijn