[Framework-Team] Re: Fwd: Including a Documentation section in each PLIP
Israel Saeta Pérez
dukebody at gmail.com
Sat Nov 15 16:49:39 UTC 2008
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.
IMO we should try to update at least the most general documentation
(manuals and important tutorials) before each release. To avoid
problems, we could start with 2 or 3 easy-to-document PLIPs and see if
we can manage to get relevant docs updated timely.
@plone-docs: read the whole thread at http://is.gd/7DTi .
More information about the Framework-Team