RE: [Zope-dev] Product standardization
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
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
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
Chris McDonough wrote:
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.
Great! How does one put in a request? :)
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.
Agreed.
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.
I think getting the process started (initially I agree aiming for some short guidelines document) is most important. The core document can grow as required. I'd be willing to help writing/editing such a document, but I definitely can't do it without more expert help. Regards, Martijn
participants (4)
-
Amos Latteier -
Chris McDonough -
Martijn Faassen -
Martijn Faassen