On Mon, 16 Aug 1999, Hadar Pedhazur wrote:
We give it away, and support the hell out of it, and yes, documentation lags (sometimes too much).
Patrick Responded:
I'm afraid I simply can't *afford* to sympathize with your last sentence and frankly I'm becoming very weary of seeing that sentiment put forth.
I understand that completely. I'll respond more fully below.
As much as I may disagree with some of the ideas espoused by Richard Stallman, I wholeheartedly agree with his notion that application software lacking properly prepared documentation shouldn't be released until that defect has been fixed. Period.
Well, then there won't be too much free stuff of serious value given away. We're yet to see a company like Digital Creations make serious money over a long period of time. We're pioneering a space, and paying dearly for the priviledge. We're glad to do it, but exactly how would all of the current "Powered by Zope" sites, testimonials, case studies, etc., be accomplished if there was no software, while it awaited the documentation?
I doubt that the documentation writer DC has hired will ever catch up in the current climate.
You're correct. It was my hope that the ZDP effort would help to ameliorate that problem. I, for one, think they've made a very admirable dent. I also think that the list, while a difficult thing to search, is an invaluable resource to the hardy. To me, the problem with the docs were not a complete lack of documentation, but rather a lack of organization. Unfortunately, that allowed us to cede such an important effort to a vigorous group of volunteers. I say "unfortunately", because since then, 2.0 introduced so many new concepts, that clearly reorganizing the old docs alone, would not give us the clarity that we would need.
I doubt that DC will ever achieve its goals until that problem is addressed. If I were running DC, I'd declare the following policy, effective immediately:
"""The current feature freeze on 2.0 will now be supplemented by a development freeze. All developers, salespeople, in fact anyone with a brain and a pair of eyes and hands, will reassign themselves to supporting the documentation effort until that effort has come abreast of the current and near-term development. Henceforth, we will *not* release until documentation is in hand."""
That may be a very realistic thing for us to do, seriously. However, 2.0 is still not out, and it would have been wrong (IMHO) to hold off the release that brings so many new things (ZClasses, multi-threading, ZCatalog, etc.) until they were all documented. I realize that the effort on some people seems interminable. For that I am sorry. Sorry not only for them, but for us, for having lost an opportunity for another evangelist. However, for each of those, there are many people who are doing amazing things with Zope, witness Squishdot, Phillip Eby's DTML tags, and many more that I should pay homage to here... If we had waited for the docs to be updated, they'd only be starting their efforts at some undetermined point in the future, and the Zope world would be a sadder place for that. Please don't misunderstand this response. I think it's a critical problem. However, I also think that the state of the current docs, bad as they may be, are surmountable, and have been surmounted by many people. After all, you do have the source. I know that this isn't a mass market answer, but Bradford himself gave an excellent example of how easy it was to master Python, so those that want the power of Zope sooner, should avail themselves of this (last-ditch) avenue.