Re: Proposal to manage documentation similar to (or along with) core software.

Helloes everyone!

Part of what what you mention has already being happening, although 
rather informally. Long time ago a group of "Documentation Team Editors" 
was formed, mimicking the FWT, dividing the documentation into the 
different sections as development, theming, managing content, etc. and 
assigning one or two editors to each of them.

The members of this team were responsible of approving/rejecting 
submitted documents, taking decisions about the documentation and 
gardening the docs, among others 
(http://plone.org/documentation/kb/plone-org-documentation-editors-roles-and-responsibilities).

Time passed by and some editors like Veda or JoAnna stepped down (see 
the list of current editors at 
http://plone.org/documentation/kb/documentation-team-editors). The 
problem, as Martin points out, has almost always been lack of 
committment due to lack of motivation and time in general. Some people 
joined the Editors team and left it after short time and little work, 
due to lack of motivation I guess.

I don't really know how to fight against the lack of motivation among 
the people working on documentation, including me. I like to think that 
lowering the contribution barrier with the division 
manuals/knowledgebase will help, but with the UI work and the 
policies/permissions/licenses work apparently stalled, I don't know if 
we will manage to see the benefits of the knoweldgebase soon.

What I understand from Alex proposal is that he wants to formalize the 
process a bit more and make it release-wise. I like the release-wise 
idea, since it helps (at least in my mind) to set a clear objective 
(document the next major version) and I also like the rotation idea 
proposed by Ricardo Newberry, for not burning the people too much.

Now to comment the steps:

Alex Clark wrote:
> Hi all,
> 
> I'm sure this has come up before but I'm wondering if it could gain some traction now.
> I've been lurking in #plone-framework and I really love the proces, and daily grind
> of work and activity that goes on in there. I'm wondering if we could inject some of 
> that enthusiasm and activity into the documentation project.
> 
> We have soooooooooo much good documentation out there, but very little structure
> or organization AFAICT (and not due to lack of effort, I know people have
> been working hard at various levels).
> 
> To that end, I propose we focus on the following:
> 
> 0. Elect a "doc team leader" similar to the FWT leader, and have
>    the Plone Foundation pay a small amount to them to encourage
>    them to do a good job. It could even be the FWT leader, but
>    I doubt Eric or Hanno want the additional responsibility.
>    I nominate dukebody :-).
> 

I've already been working on the Plone 4 documentation for some time, so 
I guess I wouldn't be a bad "leader" for this release. Are we talking 
about 4.0 only, or 4.x?


> 0.5. Elect a "doc team", again mirroring the FWT process here.

http://plone.org/documentation/kb/documentation-team-editors is the 
current list of "doc team editors", and 
http://plone.org/documentation/kb/plone-org-documentation-editors-roles-and-responsibilities 
their responsabilities as stablished two years ago.

> 1. Identify all the resources we care about, e.g.:
> 
>     - FAQs    
>     - Manuals 
>         - Plone Core Developer Reference   
>         - Developer Manual   
 >     ...
>     - Knowledge Base  

We care about everything and have a quite long list of more-or-less 
defined tasks at https://dev.plone.org/plone/report/8 .


> 2. Identify a subset to version and release.
>
> 3. Work toward a release. Ideally one that corresponds to a
>    software release, but I suppose that is not mandatory.

The problem is that documentation is a kind of moving target never 
finished. I cannot say "oh yeah, I've sucessfully documented portlets", 
because there will always be use-cases and functions not explained. Some 
parts of Plone are almost completely undocumented (e.g. some Plone 3 
PLIP-based features). I don't really know how to identify a subset of 
tasks and release if it isn't corresponding to a software release.


> 4. Have fun and profit.
> 
> 5. Hang in #plone-docs 24/7.

This is the easy part. :)

-- israel


------------------------------------------------------------------------------
Download Intel® Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev