[Framework-Team] Re: Fwd: Including a Documentation section in each PLIP
wichert at wiggy.net
Sat Nov 15 17:01:24 UTC 2008
Previously Israel Saeta Pérez wrote:
> On Sat, Nov 15, 2008 at 5:08 PM, Wichert Akkerman wrote:
> > Previously Martin Aspeli wrote:
> >> 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.
> > I would much rather see the equivalent of the what-is-new-in-python-x.y
> > documents: a thorough explanation of every change, its rationale, and
> > the inpact that has on both existing and new code. That would then be a
> > very useful starting point for the documentation team to update/extend
> > other documentation.
> If the documentation has to wait for version releases it will always
> be behind code, which leads (among other causes) to the actual state
> of some areas of the plone.org documentation: outdated. Of course the
> documentation team has great responsibility here, but trying to keep
> code as important as code will help.
You misunderstood my point. What I want to see is for each PLIP to have
the equivalent of a section of the what-is-new-in-python-x.y documents.
That does not require waiting for a release.
Wichert Akkerman <wichert at wiggy.net> It is simple to make things.
http://www.wiggy.net/ It is hard to make things simple.
More information about the Framework-Team