[ZDP] Documentation atrophy, and an offer of assistance

[Chris McDonough]

On Tue, 2002-10-15 at 09:10, Adrian van den Dries wrote:
> Hello!
> 
> Please forgive my posting to this address; I could not find an
> appropriate mailing list (ZDP appears to just receive zope book
> comments).  I just hope it doesn't bounce.

This is the appropriate maillist, thanks.

> I would very much like to help with reorganising the Zope documentation,
> both "official" and user-contributed.  How can I get started with this?

Well, you can do a number of things:

- contribute to the "new.zope.org" project at
http://www.zope.org//projects/nzo/FrontPage .

- help edit a chapter of the Zope Book

- organize an effort to contact howto authors and get them to either
deprecate or update their howtos.

> It seems that the current documentation has atrophied to the point of
> uselessness.  So much of the documentation is either too outdated, too
> specific, or just too numerous to sift through.  For example, I have
> spent many hours trawling the docs for information on "best practice"
> Zope setup.  Most of the contributed how-tos are outdated Zope/Apache
> information, and there is practically nothing regarding real
> "enterprise" Zope/ZODB/ZEO administration, just a mish-mash of Proposals
> and what-have-you regarding some alternative storages.

There should be canonical information about this in the Zope Book.  Note
that there is a new Zope Book edition for Zope 2.6 at
http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/index_html
.  It has a few new chapters and many chapters are rewritten.   Maybe
there should just be chapters like:

  - Integrating Zope with Apache

  - Maintaining Zope

(Note that the second chapter already exists in skeleton form and the
first has some overlap with the Virtual Hosting chapter).

These could use some fleshing out.  If you wish to contribute, use the
"STX Source" link at the top of a chapter, edit the structured text, and
mail me the result.  (also, make sure you edit the Zope 2.6 book stuff
rather than the 2.5 book stuff).

> I would like to help make *all* documentation pertinent and current,
> and, most importantly ALL IN ONE PLACE.  This is particularly important
> for technical decision-makers.  The scope of this is necessarily large:
> it covers not just the Official docs and user how-tos, but the
> development projects/proposals also (at least to the extent that ideas
> from here are made available as user docs).

Well, if this idea could be broken into smaller achievable goals, I
think this might fit hand in hand with the new.zope.org project.

> I am so frustrated with being frustrated that I am offering to do
> whatever it takes to get a *real* ZDP moving.

Well, thanks, and hope to hear from you!

- C