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

On 15/04/2010, at 9:30 AM, Alex Clark wrote:

> On 2010-04-14, JoAnna Springsteen <[email protected]> wrote:
>> Excellent summary Israel!
>>
>> What aclark has proposed is really nothing new. We've been talking
>> about doing this since the google doc sprint in 2007. The goal for  
>> the
>> past few years has always been to release up to date docs when a new
>> release of Plone is sent out.
>
> Right, but up to date docs != versioning. We have not *versioned* and
> *released* docs to date. That needs to start happening now with  
> Plone 4 IMO,
> so that by the time Plone 5 rolls around we can look back and say
> "Ahhhh, these are the docs we shipped with Plone 4".

+10. All the manuals should have separate versions viewable with urls  
that clearly state the major plone version to which it belongs. If  
that means we no longer improve the plone3 user guide after plone 4  
comes out I think thats fine IMO. I don't know if versioning is built  
into the new proposed UI for the manuals section.
I can;t see how KB content is going to be practical to have separate  
versions so I guess it will have to keep the existing way of stating  
which versions of plone the doc was written for.

>
>> The key issue here is getting people to commit to volunteering and
>> then ensuring they follow through with their committments.
>> 1-2 hours a
>> week is an under-estimate of the effort required. Documentation is
>> time intensive and it will always be a moving target, as Israel
>> mentions.
>> A lesson learned to keep in mind is that no matter what plans you  
>> make
>> or how much you formalize the process, if you can't get people to
>> follow through on what they say they will do, you can't make  
>> progress.
>
> Pay the release manager and the doc team will either deliver, or  
> suffer
> the consequences. ;-)

+1 to paying the release manager. It's a stressful job. But are you  
sure it should be the same person making decisions? for example  
deciding that we need to concentrate on portlets documentation vs  
workflow documentation on the plone 4 release? or deciding if we  
should use the sphinx developer manual vs the current one in  
plone.org? Is the release manager the right person for that job? it  
seems to me the qualities of the enforcer vs the decision maker are  
very different.

>
>> j.
>>
>> ------------------------------------------------------------------------------
>> Download Intel&#174; 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
>
>
> -- 
> Alex Clark · http://aclark.net
> Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admin
>
>
> ------------------------------------------------------------------------------
> Download Intel&#174; 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
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs


------------------------------------------------------------------------------
Download Intel&#174; 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