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