Agreed we need more/better documentation. Am very glad the effort is being put forth to do as much on the volunteer basis as is being done, and that the Zope Book continues to be made online available (yay). That said... <2p>The approach taken by JBoss.org has certainly paid dividends for them. Their emphasis from near the beginning has been to focus on developing and selling high quality documentation and lots of training courses, which helps build a well-developed workforce around the product. It also (of course) sets them up as the obvious leaders when it comes to developing enterprise-quality projects using JBoss. I know next to nothing about Zope corp itself, other than that their corporate goal seems to be to offer top quality consulting services around their software. That's the same as JBossgroup, but the JBoss approach to doing so (by advancing the quality of all JBoss developers through better education) also has helped propel enormous growth in popularity of that product -- which, of course, leads to more and better jobs for JBossgroup because JBoss gets increasingly high visibility. So... Zope - great product, tricky to understand, growth good but slow JBoss - nearly great product, great docs and corporate training, growth seems to be through the roof. I think Zope Corp. could likely benefit a great deal by sponsoring/leading the way toward *First Class* documentation for us all. I'm not knocking ZC or their approach -- they do a lot for the Zopistas -- but at a minimum such an effort would pay for itself for ZC (write once, sell many docs, rewrite often, sell subscriptions), and it would increase the trickle of newbies into the fold, and make MUCH more palatable the adoption of Zope the platform into enterprises of all types. </2p> =P *** DTML is dead! Long live DTML! *** At 12:28 PM 11/11/2003, Dylan Reinhardt wrote:
On Tue, 2003-11-11 at 07:40, Andreas Jung wrote:
The Zope API Reference, useful as it is, is far from complete. For example, it does not answer the O.P.'s question.
This raises my old question: why aren't there people in the community willing to contribute to the documentation?
Our documentation is approached in such a way that participation is heavily fragmented and rendered considerably less useful. Zope's single biggest documentation problem is that there is far too much of it that is obsolete and/or non-authoritative. Recruiting new contributors is, at best, a secondary problem.
IMO, Zope is burdened by some early choices that were made about how documentation should work. We have put a lot of though into the *technical* questions of *how* to host documentation but little apparent thought into what makes documentation useful or not.
I'm working on a side project that I think may provide some of the usefulness questions. At the moment, there's nothing to show, but I expect to put something up in mid-January. If someone else gets around to solving these problems before then, great. Otherwise, we'll see if what I'm cooking up helps out at all.
Dylan