[ZDP] Documentation Plans
Thu, 19 Aug 1999 23:33:23 +0200
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
> 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
> 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...
> 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!