[Zope] Documentation

Stephan Richter SRichter@ixl.com
Mon, 16 Aug 1999 17:02:40 -0500


Hey Zopsters,

Here are some lines and an analysis of the Documentation problem as I observed
it:

The Problem:
---------
I was talking to Brad Hull last week and he was very excited about Zope. It is
now up to us to find out how he would write an E-Mail titled: Giving up in
Frustration.
The problem is not, that the information is out there (in the community), but
the information is in the people's head and not on paper or in a file. That is
the real problem.

The Solution:
---------
The solution is to transfer (download?) the knowledge from the Zopster's heads
down into screen and print media. Together we can make it happen. One guy
certainly cannot do the documentation himself.

How do we bring the solution to reality? I wrote a rather lengthy letter to
Paul Everitt this weekend.describing some of the tools which could help us to
do this. For example I suggested to have a FAQ that is built by the community,
by providing the Zopsters tools to add questions and answers directly to the
FAQ. This way the editor only needs to check for grammar and spelling in the
FAQs.
Another way would be to build some kind of Reference Manual, which lists all
DTML tags, Products, DB Adapters and other objects. The community can then add
descriptions and attributes, methods and so on to make the Reference complete. 

When and how to Start:
----------------
We need to start now. I would be willing to take the task of developing a tool
that will allow us to create FAQs and the Reference manual. I appreciate any
help I can get by providing me with comments and suggestions of how the tool
should look like and how it should perform. If anyone wants to share the effort
with me PLEASE contact me.
If Digital Creations already started a tool like that please contact me also.

Regards,
Stephan
--
Stephan Richter
iXL - Software Designer and Engineer