On Sat, Nov 15, 2008 at 2:15 PM, Martin Aspeli wrote:
> 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.

We're likely moving towards splitting documentation into official and
community parts, with the official one involving a continuous review
process to ensure it's up to date and reliable.

I agree with you: neither the PLIP submitter or the Framework Team can
browse through *all* existing docs looking for obsolete practices, but
we should try to document each new feature or change in at least one
"authoritative" document, i.e. theming, archetypes or GS manuals.

A documentation section with a few lines in each PLIP identifying
changes in development, administering, customization or UI, maybe
linking a example document that must be updated should be enough.

Is this simple enough to start without clogging up the PLIP submit and
review process? I hope so.

-- Israel

_______________________________________________
Framework-Team mailing list
Framework-Team@lists.plone.org
http://lists.plone.org/mailman/listinfo/framework-team

Reply via email to