[Framework-Team] Re: Fwd: Including a Documentation section in each PLIP
Israel Saeta Pérez
dukebody at gmail.com
Sat Nov 15 15:17:18 UTC 2008
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
> 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.
More information about the Framework-Team