Re: [Framework-Team] Re: Fwd: Including aDocumentation section in each PLIP

> -----Original Message-----
> From: Wichert Akkerman [mailto:[email protected]] On Behalf Of
> Wichert Akkerman
> Sent: Tuesday, 2 December 2008 5:49 AM
> To: Dylan Jay
> Cc: 'JoAnna Springsteen'; 'Israel Saeta Pérez'; 'Plone Docs List'
> Subject: Re: [Plone-docs] [Framework-Team] Re: Fwd: Including
> aDocumentation section in each PLIP
> 
> Previously Dylan Jay wrote:
> > Hi,
> >
> > My impression from the thread was the framework team aren't resisting
> > because they don't value documentation. They are resisting because the
> PHC
> > soup is too hard to "know well".
> 
> I don't think there's been any discussion on it actually. But indeed, I
> do not think it is reasonably to ask PLIP implementers to find all
> relevant entries in PHC.

That was my take on the framework team discussion. That developers updating
the actual Plone.org documentation is too hard and even linking to the docs
which should be updated is pretty hard.
 
> What I want from PLIP implementers is the following:
> 
> - a description of what changes for developers (ie new patterns to use)
> - a description of what changes for users (ie new patterns to use)
> - proper documentation for new features.
> 
> All or none of those may be doctests, as long as they are readable
> documentation, not tests with some narrative in between code snippets.
> 
> That should give the documentation more than enough data to find and
> update documetation on plone.org

I think this would be a great improvement but this means it’s the doc teams
job to update the documentation which I think is what is currently broken in
this process and will result in an overloaded doc team and docs not done.

Why not go one further and say if the developer is changing the api by
creating or changing core modules its also their job to directly alter the
api/developer documentation. User documentation is still probably better
done by the doc team. 
If the documentation is unintegrated then its likely to stay that way.

Imagine a new PLIP process like the following:-

1) PLIP created which includes references to sections of the Plone dev
manual that will change and users manual changes
2) implements changes in a module, including some doctest style
documentation
3) checks out collective.sphinx.plonedocs and creates a branch for their
PLIP.
4) edits rst files in plonedocs such that it now links in their new module
and its documentation and also changes any other parts that are outdated by
this change. The result is a single consistent readable manual.
5) using buildout compliles the documentation so it can be read.
6) submits the plip for review which now includes a reference to the
plonedocs branch.
6.5) doc team editor is now part of the PLIP review process and reviews the
developer documentation changes to see if they are acceptable
7) if accepted the plonedocs PLIP branch is merge into the trunk and then
the resulting manual uploaded into Plone.org as the bleeding edge upcoming
Plone release manual.
8) doc team go and update the user documentation in the Plone manual based
on the guidelines in the PLIP
9) at the time of the next Plone release the sphinx.plonedocs gets tagged
and version pinned and the Plone.org upcoming manual becomes
Plone.org/dev/manual/3.3 and a new upcoming manual started. Same for the
user manual.


That’s really cool process I think. If you are changing the Plone core, you
are changing the Plone core docs and both get reviewed together. 
It's not too onerous is it?




> Wichert.
> 
> --
> Wichert Akkerman <[email protected]>    It is simple to make things.
> http://www.wiggy.net/                   It is hard to make things simple.


-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/