RE: [Zope-dev] Product standardization
Chris McDonough wrote:
Though I can't speak at all for DC regarding this matter (this is probably Chris Petrilli's or Brian Lloyd's territory),
Can you get them to speak up on this issue? :)
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 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 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).
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:
* appoint a number of 'Product reviewers'. Basically the Digital Creations product gurus should appoint the first product reviewers (at least 2), which hopefully include themselves.
* A particular version of a product is considered to be 'Zope compliant' if at least 2 product reviewers did a thorough review and approve, and no product reviewer at all vetos anything.
* Set up a mailing list, Zope-review, to handle product review discussions only. The product reviewers are subscribed, along with product developers who want reviews, and anyone else that's interested. The list discussions may by necessity diverge into debates about standards and guidelines. It may also go into technical discussions on product development, but ideally the latter discussions should be moved to Zope-dev so more people can profit from the information; development questions should go to Zope-dev too.
* If a product developer finishes a product that the current product reviewers think is good (and substantial enough), such a product developer can be appointed by them as product reviewer him or herself. Such a developer should be nominated by a product reviewer, and no other product reviewer should veto the appointment.
* Being a product reviewer is of course voluntary; you don't have to do anything or to accept any appointment. The idea is to bring structure and some dependability to the review process, not to enforce anything. Nobody _has_ to go through review. And there's of course the open-source ego-boost effect of being able to say you're a 'Zope product reviewer'; if you are that, you *must* be a Zope guru, eh? :) This status effect will hopefully help motivate people to participate in the review process.
* Participating developers that are not official product reviewers may of course review each other's code too; this is only good for everybody involved. Such informal product reviews will informally count when official product reviewer status is considered.
* Care should be taken that all this procedure does not actually slow down the development process. The entire review process is voluntary; you may still distribute unreviewed products. The goal of the process is to improve the design and code of both Zope and products, and to get to an idea of what it means to be 'Zope compliant', not to make things more difficult (in fact, this should make everything easier!).
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? Brian Lloyd brian@digicool.com Software Engineer 540.371.6909 Digital Creations http://www.digicool.com
Brian Lloyd wrote:
Chris McDonough wrote:
Though I can't speak at all for DC regarding this matter (this is probably Chris Petrilli's or Brian Lloyd's territory),
Can you get them to speak up on this issue? :)
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:
[snip references to info]
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 don't think the only goal should be better and more documentation and information; I think there should be a direction towards a more formal style of standardization. Should and shouldn't. And guidelines. Things for GUIs, for instance; "the submit button should be spelled 'Ok'". Things like "there should always be a 'security tab', except when". The process to establish these rules and guidelines is something that should happen in the community, as the community of product developers can come up with *issues*. And there are lots of issues. So, we need to have a better *process*, not only better documentation. This is *not* the old 'we want better documentation' thing; we've said that already and it's well known.
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 don't think so. The introductory material should consist of howtos and tutorials, a story on how to do it, along with examples. Then there's reference material that describes what interfaces are used where and why and how. Then there are guidelines that describe what interfaces (etc) you *should* use, and how exactly, and why, and when not. The intro material can be improved by the documentation process. The reference material too, but I think it might be driven by the guidelines process. That is, someone will come up with a guideline. People will ask why that guideline? Why mixing ZopeFoobarInstanceFactory there? Why override method extended_nonsense_delimiter() over there? Then reference materials will be created as a result. [snip my peer review process proposal]
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).
Perhaps zope-dev is okay, but..
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?
Yes, the burden is on you guys, which is why I proposed you appoint a number of 'official product reviewers'. Once you actually start reviewing products (I have some candidates :) you can actually _know_ what guidelines to write, what documentation to generate. You see what Martijn keeps doing wrong. You see what Martijn is missing. You can tell Martijn that he doesn't need to do that particular voodoo there, and why. Martijn might ask things you hadn't thought of, too. If you set up a scheme where you have formal product reviewers, those product reviewers might need a medium in which to communicate, which is why I proposed a seperate mailing list with that goal only. I just want a way to address them for product issues. Anyway, this sounds like I just want to get my products reviewed by you guys. This is true, I do. :) I realize there isn't enough time and manpower to do that, which is why I am suggesting a mechanism on how new official product reviewers can be created. I'm also suggesting a way towards quickly generating documentation that people need in practice, which will make future reviewing less difficult. Anyway, don't only work on documentation for this. Don't only set up a documentatin process, even (though very important!). Also set up an actual process of people reviewing each other's code in a public and clear way, with clear goals (better products and better documentation). Regards, Martijn
participants (2)
-
Brian Lloyd -
Martijn Faassen