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