[Zope-dev] Product standardization

Chris McDonough chrism@digicool.com
Fri, 07 Jan 2000 01:56:24 -0500


Without getting too deep into discussion of how a task like this gets
started and what its goals should be, I am willing to loosely "review" a
few products as requested and as time allows.  With a couple of other
people, we should be able to at least build a list of desirable product
features after comparing a few products to one another.  After that I
suggest that we can revisit the topic of coding/UI/documentation
standards armed with findings.  Personally, I'd be happy with the goal
of creating a (very short) "straw man" Product Style Guide, armed with
which we could decide to proceed on more formal "standards" or punt.

Martijn Faassen wrote:
> 
> 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
> 
> _______________________________________________
> Zope-Dev maillist  -  Zope-Dev@zope.org
> http://lists.zope.org/mailman/listinfo/zope-dev
> **  No cross posts or HTML encoding!  **
> (Related lists -
>  http://lists.zope.org/mailman/listinfo/zope-announce
>  http://lists.zope.org/mailman/listinfo/zope )

-- 
Chris McDonough
Digital Creations, Inc.
Zope - http://www.zope.org