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

[Dylan Jay]

Martin Aspeli wrote:
> 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.

I agree that the current structure of plone docs makes it too hard to 
find docs that need changing.
A ooncise manual of the api would be more manageable though right?
I'd suggest waiting for that.