[Zope-dev] Product standardization

Martijn Faassen m.faassen@vet.uu.nl
Thu, 06 Jan 2000 19:29:18 +0100


Amos Latteier wrote:
> 
> Brian Lloyd  wrote:
[snip]
> > 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.

No, I don't think this kind of thing belongs hidden inside a tutorial.
It doesn't even belong in a reference. The "should" and "shouldn't"
aspects of product development should at least be seen as a seperate
concept. That will hopefully help you improve everything; products *and*
documentation.

> > > > 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.

That's true. How many clues about useful documentation would you gather
from it, though? I'd imagine lots.

> I personally don't have this kind of time, but others may.

Nobody does. :) But in practice, we *do* look at each other's code. To
write good documentation about coding something, you do need to look at
current code for coding practices. To write documentation about an
existent API you need to look at the code too. We may not call that code
reviewing, but let's.

> > > 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.

Of course this is very important.

> I don't think that we need an official
> good-Product description.

Why not? Anyway, I am clamoring for a process with the *aim* to generate
a 'good product' specification. I don't think we can come up with such a
spec now. It's obvious from below that nobody really knows. We simply
need a process to find out what it could be. It'll be a moving target,
but that doesn't matter.

> That said, here's a quick list of what I think
> a good product should do:
> 
>   * correctly subclass existing Zope classes

Right. We should have a list of which Zope classes do what, and why you
should subclass them, and what does it mean to be 'correct'. And what
you should do with them after subclassing them. And what you shouldn't
do.

>   * correctly handle permissions

I think this too needs documentation but also guidelines. What to call
the new permissions you come up with? What kind of defaults would you
set, and why? What are the _current_ permissions about, and how to use
them with your own product? What would be wrong to do? What would
introduce security holes? What should I do with my methods? Put _ in
front to shield them, or not, and if I don't, do I add it in security? A
thousand questions both documentation and guideline oriented.

>   * correctly handle persistence

I've seen guidelines and doc for this floating around, but I'm still
unclear on what my options are and what I shouldn't do.

>   * present a reasonable HTML UI to users

That conforms to Zope standards. It should similar to the rest of Zope.
What do we do when Zope's UI changes (Mozilla, for instance). What will
definitely help in that transition process is a good clue what the
current HTML UI is actually about.
 
>   * present a reasonable API to DTML programmers

Do we know what a 'reasonable' API is?

>   * include some documentation

Is there some auto documentation tool coming up? How will it work? How
will my documentation conform? Are there documentation standards?
 
> A good product mostly is one that works correctly ;-)

That's why I said nobody really knows what a good product is. What does
'work correctly' mean? :) Correctly for end-users, developers, the
original developer, who? It should also work consistently, it should fit
in with the rest of Zope. We don't know what 'fitting in' means well
enough right now.
 
> 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. 

Hm, you're changing your tone here; before you said tutorials were
enough. :)

> As for getting this done I see this
> general procedure:
> 
>   1. identifying areas that need recommendations

I hope I offered some help there. Again, reviewing code will help with
this identification process. I can't do it, as I don't have a clear idea
yet on what my code _should_ be like, regarding Zope.

>   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.)

Yes, it should be a product of a community process.

> 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.

I think this process of generating recommendations could be helped
immensely if we looked at each other's product code.

Regards,

Martijn