[Zope] The agony of the ZOPE Documentation

Jerry Spicklemire jerry@spicklemire.com
Wed, 24 May 2000 17:31:52 -0500


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.

How can such a critter be set up?

Thanks for considering a crazier idea,
Jerry S.