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

Philipp von Weitershausen philipp at weitershausen.de
Mon Mar 20 06:29:10 EST 2006


Martijn Faassen wrote:
> Using proposals for communicating development-level changes is not
> ideal. This is why Python has a separate "what changed in Python 2.x"
> document series, which is actually readily comprehensible, as opposed to
> many of the PEPs.

And kudos to Andrew Kuchling for writing those! I don't think anyone in the
Zope 3 community has the time do write something like that.

Perhaps proposals aren't ideal for communicating development-level changes, but
then again, that's what they are describing, right? Proposed development
changes...

> So, suggestions to improve the proposal process for Zope 3 sound fine,
> but they don't target the issue I've been trying to point out. I do not
> see this as doubling the information - there is frequently a large
> difference between a proposal for a Zope 3 core developer audience and a
> description for a Zope 3 developer after it has been done.

Yes and no. Some of my proposals I used almost unchanged as doctests later on.
In the "Reducing the Amount of ZCML Directives" proposal I've tried to explain
what certain directives are to be replaced with. I think both is very
developer-friendly. As you said yourself before, I'm almost "there" (meaning
developer-level documentation).

> In addition, there is frequently a difference between what's been
> proposed and what exactly has been done.

Yes and even with proposals and the process related to them as it is that isn't
really acceptable. In the end, proposals should be updated, at least the
"Implementation status" section should mention how far the implementation went
and where it deviates.

As said, I'm not saying that proposals the way we have them now are sufficient.
But, with just a little more formalization to the whole process, I think they
could serve for what you want.

Philipp


----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.


More information about the Zope3-dev mailing list