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

On 2010-04-14, Dylan Jay <[email protected]> wrote:
> So whose job is it to prod those finishing the changes to the kb ui?

Not the doc team's problem, IMO. The doc team should write and release docs, period.
When a release is ready, it should be published to plone.org. If there are 
problems doing that, then it's the website team's responsibility to fix it.
This is not unlike the core software / installer dance.

> The editors team is great but it isn't the  same as the fwt beacause  
> they just review instead of do the work themselves. So if we are to  
> model ourselves on the fwt process what do we need?
> What we need most is release manager for docs. This is something  
> joanna was fantastic at and will be sorely missed for. A cat herder  
> and finder of volenteers. Not someone to set the vision but to enforce  
> it.
> Secondly I think we need a person or team with vision and authority to  
> make decions about which proposal to go with so there is a clear  
> direction. Thats what a leader does, listens to everyone and takes  
> responsibilty for the decision. This is the equivilent to the fwt I  
> think. I think in the past we may have confused the team doing the  
> work with the team making decisions. It's hard to have vision when you  
> feel like your the only one who is going to do it ;).

Yup, the Doc team leader sets the release date, work schedule, 
deliverables, etc. and then enforces them. What's needed now IMO
is to get foundation buy-in on paying the doc team leader. 

> Dylan Jay
> Technical solution manager
> PretaWeb 99552830
>
> On 15/04/2010, at 6:16 AM, Israel Saeta Pérez <[email protected]>  
> wrote:
>
>> 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&#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
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs


-- 
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