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

[Martin Aspeli]

Israel Saeta Pérez wrote:

> 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.

I am not convinced that the Documentation Team at this point has enough 
structure (both in terms of the actual corpus of documentation, and the 
team itself) to facilitate this kind of process. There's been some very 
encouraging movements on the doc list in the last few weeks, but like 
Raphael, I'd be worried about this clogging up a process that's already 
stretching the current team.

I do agree that documentation should be part of PLIPs. One simple thing 
would be to just have a free-text on the PLIP that identifies the 
documentation that is either required or extant for the PLIP, so that 
people who look at the PLIP later can find a pointer to where there's 
more documentation.

However, I think it's too much to ask at this point that the framework 
team or PLIP authors go through all existing documentation looking for 
things that may be outdated.

Martin

-- 
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book