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