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/