[Zope] ZDP

[Amos Latteier]

At 06:59 PM 2/5/99 +0100, FR Chalaoux wrote:
>I often have problems with zope documentation. Maybe it could be  
>an idea if community lake information to think about a ZDP  
>(Zope Documentation Project)?

I like this idea. I would be very happy to open the documentation process
up to more community participation.

I understand that Zope documentation can be frustrating, and I'd love to
hear about your ideas for improving things. It is my hope that now that we
are getting more people on board we will be able to make improvements in
documentation and in enabling community participation in general.

Let me briefly give some of my views on the documentation situation:

* Understanding what Zope is and what you can do with it is hard.

I think we need to restructure our web site to give a better and simpler
explanation of what you can do with Zope and why you'd want to use it. We
also plan to include more informative and useful default content, including
more examples.

* Finding out how to do a specific task with Zope can be hard.

The are a couple reasons for this. We do not have a simple way to search
the documentation. The documentation is not as clearly labeled as it could
be. Some features are still undocumented (but not many). Zope can be used
for many, many different things, so the range of problems is quite
large--from how to best compile and configure Apache on a given flavor of
Unix, to how to best write SQL for a given type of query, to how to best
produce HTML select widgets with DTML, to how to minimize FTP denial of
service attacks, to the rules of Structured Text mark up, to how best to
convert between different Python date and time formats.

I think we need to move to a better classified documentation system, and
provide a system of searching the documentation. We should probably also
try to cull interesting information from the mailing list to beef up the
support and how-to documentation.

* Getting your question answered on the Zope list can be hard.

The Zope list is getting a lot of traffic. In addition, many questions are
rather involved. Despite this, many questions actually do get answered.
Hopefully, the upcoming list split will help by segmenting list traffic and
help more questions get answered.

* Figuring out how to extend Zope can be hard.

The Zope API is complex, and the Zope internals are large. It can be hard
to understand the Zope overall design well enough to decide if you should
create a Folderish Product, and new DTML tag, or an External Method.
Figuring out what methods are available to you, and which ones you might
want to use is also tough.

I think that the Product API tutorial helps. Also the Object Reference is
an invaluable aide. Extending Zope is not for everyone. Perhaps the lever
and Zope classes will eventually lower the threshold so that more people
will be able to extend the platform.

I look forward to a better documentation process that will help more people
get the most out of Zope.

-Amos

--
Amos Latteier             mailto:amos@digicool.com
Digital Creations         http://www.digicool.com/