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