[Framework-Team] Fwd: Including a Documentation section in each PLIP

Israel Saeta Pérez dukebody at gmail.com
Sat Nov 15 10:49:36 UTC 2008


On Sat, Nov 15, 2008 at 4:57 AM, Raphael Ritz wrote:
> Steve McMahon wrote:
>>
>> Hi Framework Team,
>>
>
> Hi Steve and Israel,
>
> first of all thanks for bringing this up.
>
> Just one personal comment from my side:
>
> I think I do understand where this is coming from
> and I really appreciate the intention.
> But (there's almost always a but in real life
> isn't it ...) lets try to be realistic:
>
> First, I'm much in favor of having the PLIP process
> as easy as possible. First and foremost we should
> be interested in ideas and implementations I think.
> Everything else should follow from there.
>
> Second, it is my understanding that much of what's
> proposed here should be the responsibility of the
> framework team. At least I usually try to point out
> where I think documentation (be it new or an update)
> is needed on an individual basis.
>
> Don't get me wrong but I seriously think that raising
> the bar for submitting PLIPs or accepting them beyond
> of what we require today already might be problematic.
>
> Others may disagree, of course, but I only want to stress
> the fact that it is one thing to formulate wishful thinking
> and another to value openness and accessibility.

Dear Raphael,

Thanks for your cents! :-)

I don't mind who actually identifies documentation that would need to
be updated, if the PLIP submitter or the Framework Team, but I'm
convinced every new feature or change should be reflected into the
existing documentation, which is IMO as important as code and
features.

If we don't document new features as we introduce them, we will end up
with obsolete documentation, as is already happening. If we don't like
raising the bar for submitting PLIPs, at least we should commit to
(really) introduce documentation in the release checklist:
 http://plone.org/development/teams/framework/process/

I'm sure the Documentation Team will be happy to collaborate with the
Framework Team to get things done timely.

-- Israel




More information about the Framework-Team mailing list