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

On 14/04/2010, at 12:54 PM, Clayton Parker wrote:

> On 04/13/2010 10:08 PM, Martin Aspeli wrote:
>> On 14 April 2010 10:03, Alex Clark<[email protected]>  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 :-).
>>>
>>> 0.5. Elect a "doc team", again mirroring the FWT process here.
>>>
>>> 1. Identify all the resources we care about, e.g.:
>>>
>>>    - FAQs
>>>    - Manuals
>>>        - Plone Core Developer Reference
>>>        - Developer Manual
>>>        - Plone 2.5 User Manual
>>>        - Plone 3 User Manual
>>>        - Plone 4 User Manual
>>>        - Plone Upgrade Guide
>>>        - Add-on Products Developer Manual
>>>        - Plone Theme Reference
>>>        - PAS reference manual
>>>        - Fix for CMFEditions
>>>        - Zope Component Architecture Manual
>>>        - GenericSetup
>>>    - Error References
>>>    - Links
>>>    - Glossary
>>>    - Books
>>>    - Demonstration Movies
>>>    - Knowledge Base
>>>
>>> 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.
>>>
>>> 4. Have fun and profit.
>>>
>>> 5. Hang in #plone-docs 24/7.
>>
>> +1000
>>
>> In the past, the problem has normally been commitment, not process,
>> but I also think we've been getting a lot more mature in our
>> documentation approach over the last few years so this may be a
>> logical step.
>>
>> Before you can do any of this, though, you need at least 5-10
>> volunteers who're willing to make a commitment similar to that the
>> framework team members do. That's probably a couple of hours a week,
>> on average.
>
> Count me in, I enjoy writing docs. We have left a lot of things in a
> half working state. It would be great to put some focus back on making
> sure the Plone docs are cleaned up and working properly.
>
> I don't necessarily think that we need to elect a "doc team" just yet,
> but electing/appointing a doc team leader would be good.

+1 for a leader. It's not clear at all who decides and what the  
process for gathering opinions is. I think maybe stevem is the leader  
now?
Count me in for being part of the team but as Clayton said a clear  
leader and process for now is enough.


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