Jimbo, I concur 100%. I am a Zope newbie (relatively speaking - since February) but I have been developing Web Information Systems since '95. My tool of choice was perl/CGI. I attended a DEVX conference in December of '99 and was introduced to Java Servlets and the J2EE spec. I knew this was the transition that I had to make, professionally. However, 100% of my work evolves around information management and publishing. J2EE doesn't immediately solve this requirement without a great deal of tooling. I saw the benefits of the enterprise but couldn't justify the effort (to my customers). In walks Zope and the lights/whistles/fireworks went off. Zope immediately provides me the vehicle to move from a 'Cottage Software' paradigm to a (sort-of) 'Industrial Software' paradigm. I am no python programmer, yet. But, with the other available tools (DTML, acquisition, ZClasses), I have been able to get the job done. I have hit a few land-mines since February. In some cases I was able to work through the problems from How-To's, others from the mail-listings. But a couple of problems have yet to be resolved. The new Zope Book is a step towards consolidating all these other doc efforts but it falls short on utility. I have many perl books on my book shelf. The one that I always go back to is my original 'Camel' book. Wall & Schwartz put the right mix of fact, fable and 'case studies' to get the imagination brewing. I don't need my hand held but I would greatly appreciate some insight on what is possible and what is not. The biggest stumbling block for me to date (and potentially the most powerful tool for me) has been connected with the nuances of ZClasses. The examples in the book gloss over the implementation details that would be the most instructive and could have saved me days of searching and swearing. I ended up searching for some ZClass products and worked through them to fill in the blanks. I see enormous potential for Zope in the Peer-to-Peer revo/evo-lution. I want it to succeed. I scream Zope at every opportunity. But, I have invested nearly 800 hours of my time to be able to talk-the-talk and now walk-the-walk. I feel quite comfortable in recommending this system as the final solution as we move to P2P. Not everyone can afford that kind of commitment. The people paying the bills certainly won't. Certainly, the API documentation could be presented better, but expand on some of that brain-storming that is going on behind those DC doors (well not all of them ... you guys need your trade secrets too), those 'what if' scenarios that would go a long way towards enlightening the masses. Eric

Please don't banish this wonderful product to Eternal Geekdom by not simplifing the documentation by putting together concrete examples on how to implement concepts and products.

In short enough geek speek. Change the language into something the rest of masses can understand. How can I use zope/API to get PAID! How can I actually make the dcworkflow or the core session or the ZPT do something. Plenty of example uses. I think they might call them case studies or something to that effect.

Thanks, -Jimbo

On Wed, 6 Jun 2001, jimbo wrote:

I believe that if you are a true developer you will/can figure out the api given the vast information available today. For example the dcworkflow product was just released. I believe the best documentation would be how-to actually use the product.

Ah, not really. Or, rather, "maybe", with the *new* products whose APIs are being constructed/documented better from the start, but if and probably only if there are either comprehensive examples or the framework docs mentioned in the proposal. IMO the biggest issue here for developers, as others have said, is clarifying/documenting the old Zope interfaces. If we get that, then new products will be even better/better integrated. This includes ZClasses. Half the problem with ZClasses is that they sort of almost work, but they break down partly because the interfaces really aren't documented very well. (I strongly recommend learning python. It's an easy language to learn. Then use real Python classes instead of ZClasses. ZClasses have their place, but if you are doing serious development they tend to get in the way more than they help, IMO).

In short enough geek speek. Change the language into something the rest of masses can understand. How can I use zope/API to get PAID! How can I actually make the dcworkflow or the core session or the ZPT do something. Plenty of example uses. I think they might call them case studies or something to that effect.

"How can I actually make x do something" sounds an awful lot like what I think the "framework docs" portion of the proposal is addressing, when you are talking about components like workflow and coresessiontracking that are used to *develop* applications. I think you will find that good API+framework documentation will either provide a good deal of the info you are looking for, or, for products that are less in the way of infrastructure components and more in the way of end user products, provide the essential foundation upon which more end-user directed documentation can built. Good end user stuff is best written by someone who understands how the product works in detail, and the API/framework docs provide the foundation to acquire that knowledge (assuming the product author himself doesn't go straight on to providing the end user docs). How to get use the API to get paid is, I think, outside of the scope of the proposal <grin>. As for the proposal itself, the mechanism outlined sounds OK to me. I do also have an issue with the Interface scarecrow in that it does not seem to cover stuff that is not specifically a Class interface. I'm thinking of module level functions in particular, but also the documentation of Protocols mentioned by another poster is of concern. So Interfaces by themselves do not seem to be enough. Where they are enough, though, I should think there would be nothing stoping someone from writing one for an existing Zope internal interface, without modifying the code (ie: no automated verification in that case). Of course, I suspect that anyone doing that grubby job would tend to want to start tinkering with the code to "clean up" the interface...which come to think of it might be something that should go in the "risks" section <wry grin>. On the third hand, there's nothing to stop the community from generating some "this is how I think it works" documentation that people with "inside knowledge" can then help tune. I think some of this happened during the original Interfaces Wiki days, and it seems to have produced good results. I also want to say that I really like the fact that this proposal makes it clear that DC understands the long term value of good developer documentation <grin>. Oh, and one final thought. It seems to me that the Developer's Guide needs to evolve into a "meta framework" document: a place to learn how the whole system fits together, and how you use the various components to build working systems. I think it's a solid start in its current form. --RDM