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

[Rik Hoekstra]

-----Original Message-----
From: Jerry Spicklemire <jerry@spicklemire.com>
To: zdp@zope.org <zdp@zope.org>
Date: donderdag 25 mei 2000 1:11
Subject: [ZDP] Re: [Zope] The agony of the ZOPE Documentation


>(forwarded from Zope@Zope.org)
>
>Jason Cunliffe wrote:
>
>Perhaps you have a better crazier idea..I hope so:-)
>
>Maybe. I too have had problems with the ZDP stuff, but not specifically
>those mentioned by others in this thread. When I try to use the ZDP I am
>impressed by the effort and sheer volume of material, but unfortunately it
>seems to be mostly supported by non-native English speakers. The result is
>that I am often uncertain that I clearly understand what the author
>intended. That leaves me in a state that is nearly worse that where I
>began, potentially more knowledgable, but certainly more confused. Now, for
>that crazy solution.
>
>If the ZDP were in some Wiki-ish form that could be edited by readers
>("Edit This Page", a la Frontier?), a new version of a page could be
>created to fix the most obvious misexpressions. The author might then be
>able to review the updates, and either approve the fixes, or clarify cases
>where a misfix has resulted from a misinterpretation, which itself is a
>verifiable indication that the original text was somewhat obscure. After a
>few passes through this process, the ZDP might be dressed up and ready to
>go to press!
>
>In a case like the proposal above, anyone willing to do some copyediting
>would be free to edit a paragraph at a sitting, if that's the all the time
>available, or a page, or a chapter. Whatever works. I know I have been
>reluctant to commit to any extensive participation simply because my time
>is very limited. Still, as tight as the schedule is, it isn't quite in the
>negative microseconds yet, so a graph per shift is better than nothing!
>
>With this in mind see the very recent post:
>
> http://lists.zope.org/pipermail/zope-dev/2000-May/005021.html
>
>This is a way to manage Zope Objects, stuff that usually lives in ZODB,
>using CVS. This can provide versioning, checkout, checkin, etc. It could be
>used as a way to let ZDP Authors know what's changed, at a very granualr
>level, to keep from having to wade through the page looking for somthing
>that isn't precisely as it was last time they saw it. ZDP is itself a Zope
>site, so this could be just the ticket.
>

Perhaps, but i think this is not necessary (though I liked the product
idea). Should you become a member of the ZDP site, than Maik already created
many such tools, including commenting, reviewing, discussing etcetera (and
search possibilities for documentation that needs it). We badly need people
for these tasks, though, and nobody has taken these tasks up yet. Mindlace
just yet announced serious involvement by DC, but we never had input from
them before (sorry to say so)

Please take into account that at the moment the whole ZDP, including
programming, writing documentation etc, takes the effort of far less than
ten people, who work at it in their spare time. Or to put it differently:

ZDP NEEDS CONTRIBUTORS, REVIEWERS, EDITORS, WRITERS

Help us out and the whole Zope community will benefit.

Rik