[Zope3-dev] Re: Proposals vs. developer docs [was: Reducing the Amount of ZCML Directives ready for review]

[Martijn Faassen]

Philipp von Weitershausen wrote:
> Martijn Faassen wrote:
[snip]
> Let me get a final statement out that perhaps is still misunderstood or
> not understood at all:
> 
> The way proposals work right now is not sufficient for what I *think*
> you're trying to achieve. That's where we agree.
> 
> However, I propose to require them to be sufficient. It would not only
> improve the documentation of changes (which is what I *think* your goal
> is), it would also actually account for our formal development process
> that we oh-so praise. Because, as you say rightfully, sometimes
> proposals aren't even implemented as they were written in the first
> place, or at least they weren't updated after they've been implemented
> in a slightly different way. I make no exception to myself here, I
> personally did this a few times (I remember at least one time with the
> Message IDs as Rocks proposal). That wasn't good.

Okay. +1 for improving the proposal procedure. And you're right - it 
will certainly help improve communication to non-core developers.

I still worry about the differences in audience - sometimes you don't 
have to explain something to a core developer that you should be 
explaining to a non-core developer, and often the things you say to core 
developers you don't have to say to a non-core developer after it's 
already done (like, say, a "risks" section). I'm not proposing we do 
anything about this now, as you're probably right that this would 
duplicate work too much. Let's just keep this difference in audience in 
mind. That's enough for now.

Thanks for taking the initiative to improve the proposal procedure!

Regards,

Martijn