[Zope-dev] Product standardization

[Amos Latteier]

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