Brian Lloyd wrote:
I'll speak up :^) I agree that there should be more/better documentation on the writing of Zope products - there is some good info out there though:
The Boring product:
http://www.zope.org/Members/gtk/Boring
The (excellent) Product API tutorial:
http://www.zope.org/Members/Zen/howto/ProductAPITutorial
Of course I will also admit that it's non-obvious how to find these gems and that it would be quite a bit better if there was "offical documentation". The current plan as I understand it is to work on getting an enhanced and updated version of the information in the ProductAPI tutuorial into the Zope Developer's Guide.
I am very slowing working on a Zope Developer's Guide. This will be a large Guide that covers things like building Python Products, ZClasses, ZPublisher, etc. Unfortunately this is a very large project and my time is very limited. We also have plans for eventually getting authoritative API documentation in place. However, this effort is not very mature yet. My hope is that we can soon move to a situation in which Guides are available through CVS and folks who are interested can participate directly in writing and editing them. This should speed up the process and also give folks advanced access to stuff if they'd like.
I like the idea of having a slightly more formal definition of what constitutes a "good" product, even if that definition only consisted of a couple of pages of "shoulds" and "shouldn't"s.
I think that this should be a part of the introductory material for the "how to write a product" documentation...
I agree. I think this is tutorial style information.
I also like the idea of a loose sort of peer review (other than someone just downloading the product, finding out it doesn't work, and posting to the mail lists).
I think that this is a great idea. The main problem with it is that it is a lot of work to review someone's product. I think it would take me a couple hours to go through someone's code and try to figure out how it works and how it could be improved. I personally don't have this kind of time, but others may.
Yes, that's another way to get the ball running quickly. How do we set this up, though? Some procedures would be in order. I've whipped up a suggestion: ... I think that peer review is a Good Thing - I share the opinion that it should be strictly voluntary and very light weight (in fact, I think that zope-dev would be a fine place for these types of discussions, rather than a separate list). My only caveat is: it will be much easier to "review" a product once there is an official description of what a good product is - so I would say that the immediate burden is on _us_ to get that out. Can you comment on this Amos?
As I stated above, we need to finish and make available more Zope Product tutorial information. I don't think that we need an official good-Product description. That said, here's a quick list of what I think a good product should do: * correctly subclass existing Zope classes * correctly handle permissions * correctly handle persistence * present a reasonable HTML UI to users * present a reasonable API to DTML programmers * include some documentation A good product mostly is one that works correctly ;-) Of course there are gray areas, like what is a reasonable HTML UI? And how should you decide what methods should be protected by what permissions? For questions like these I agree that we should come up with some recommended practices. As for getting this done I see this general procedure: 1. identifying areas that need recommendations 2. proposing recommendations 3. reviewing recommendations 4. blessing recommendations I think much of this work can be accomplished on the Zope-dev list with Zope community members and DC folks working together. (I think of these as Zope community recommended practices, not DC recommended practices.) I personally would be most interested in working on step 3. BTW, when recommendations get to the blessing stage we may want to revise Zope itself to follow the recommendation. -Amos -- Amos Latteier mailto:amos@digicool.com Digital Creations http://www.digicool.com