[Zope-dev] Product standardization

[Martijn Faassen]

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