Good day everyone! As usual let me say that the idea that people are downright mad/frustrated about Zope's docs is, in my humbly twisted opinion, a complement to the Zope project. I don't know about you, but there's a lot of software whose docs I couldn't care less about. Thanks for caring enough to bitch about it (SERIOUSLY!!). One of our near-term important challenges is to facilitate, encourage and participate in creating both a Process and Toolset to harness the documentary energy and zeal in the Zope Community. A reality of the situation is that by giving software away _some_ of the responsibility for its success falls to the user community. I believe I infer correctly that there is consensus that Zope is a technically superior product but that the nearly vertical learning "curve" is a REAL problem (visions of climbing Half Dome [http://www.yosemitevacation.com/halfdm1.jpg] come to mind)... Digital Creations has known for some time that Zope was, um, Documentation Challenged :^). We have been taking internal steps to address this. It seems (through _numerous_ discussions on the list and internally) that there are two distinct modes in which people USE documentation. People seem to either be: (a) looking something up (e.g., syntax, method signatures, fmt tags, etc.), or (b) trying to learn something Unfortunately, pre Z2 docs had a little of both mixed in and around. As a result, you found code snippets and examples in reference material and vice versa. This makes both maintenance and use MUCH, MUCH harder than it has to be. So Pam (Pam is the Technical Writer at Digital Creations) and I suggested we divide our Zope docs into these two categories (i.e., (a) and (b) above). We've spent the last several weeks TRYING to take the didactic material out of the reference material and the reference material out of the didactic material. The result is a casual naming convention... Reference documents will contain REFERENCE material (duh) while Guides are intended to be didactic material. Currently available documentation does NOT follow this standard -- however, Z2 docs (currently in development) will. The release schedule for these documents is: Date: Document ------------------- 9/15/1999: Zope Content Managers' Reference 9/15/1999: Zope Content Managers' Guide 9/15/1999: DTML Users' Reference TBD : DTML Users' Guide 9/15/1999: Zope Administrator's Reference TBD : Zope Administrator's Guide TBD : ZSQL Methods Users' Reference 9/15/1999: ZSQL Methods Users' Guide One real, near-term result of this is the upcoming Zope Administrator's Reference (ZAR). The ZAR is an INITIAL attempt to capture, in REFERENCE form, mostly from the System Administrator's (and ISPs) perspective, Zope's knobs and behavior. It should answer questions like permissions on the var directory... ('course that one NEVER comes up :^) In general, it seems that Digital Creations will continue to be primary players in the development and maintenance of _Reference_ materials. It is our hope and intent that the development and maintenance of didactic materials (e.g., How-Tos, Guides, Tutorials, etc.) is a Community function albeit with Digital Creations' active participation. For example, Jim Cain just posted a How-To on Apache. We agree wholeheartedly with recent posts on both the Zope and ZDP lists that suggest that the problem here is as much a lack of process as it is a lack of tool/format standard. For volunteering to tackle this in a measured and deliberate way let me THANK Stephan Richter! Stephan, I'll be sending you my $0.02 worth soon... :^) We have some ideas about implementation... However, before we go there, I'd like some (any) feedback on what I've said here... PLEASE, PLEASE, PLEASE -- let's try and keep the discussion of documentation on the ZDP list as opposed to the main Zope list. It gets hard to ensure that things don't fall through the cracks if valuable comments and ideas are posted to multiple venues. This is all fine and dandy to be sure. What specifically will happen in the near future? Good question. Digital Creations will bootstrap the How-To process by developing seven (7) HowTo Documents. These HowTos will treat the following topics: How-To: o Get Started with Zope? o Do interesting things with ZClasses o Use ZCatalog o Write Basic RDBMS-based applications in Zope o Write, use and take advantage of External Methods o Get Started with DTML Scripting o Perform the Care and Feeding of the Zope Database These documents will be fielded using the new Zope site's How-To capabilities and will be available in some form by 9/10/1999. In addition, we'll be working on the ability to index and offer a search interface into a lot of the Zope list traffic. Although I'm not sure exactly what will be there, we'll have something much better than we have now by mid- to late-September. Thanks for your time and attention, --Rob -- Rob Page Phone: +1 540 371 6909 COO Fax: +1 703 995 0412 Digital Creations