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

classic Classic list List threaded Threaded
60 messages Options
123
aclark aclark
Reply | Threaded
Open this post in threaded view
|

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

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.

Thoughts?

Alex

--
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admin


------------------------------------------------------------------------------
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
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Martin Aspeli Martin Aspeli
Reply | Threaded
Open this post in threaded view
|

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

On 14 April 2010 10:03, Alex Clark <[hidden email]> 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.

Martin

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Dylan Jay-4 Dylan Jay-4
Reply | Threaded
Open this post in threaded view
|

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

On 14/04/2010, at 12:08 PM, Martin Aspeli wrote:

> On 14 April 2010 10:03, Alex Clark <[hidden email]> 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.

whats in those couple of hours?

I know the current/past?? organisation of the doc team has been around  
"editors" and actually creating documentation, particularly now in the  
manuals area. Is the suggestion that this new team be more about  
making decisions rather than creating documentation?



------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Eric Steele (esteele) Eric Steele (esteele)
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by aclark
On Apr 13, 2010, at 10:03 PM, Alex Clark wrote:
> ...
> 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 :-).
>

Israel has been a pain in my ass over the past few months about some remaining documentation tasks assigned to me.

That, of course, means he'd be absolutely perfect for the job.

Eric
------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
claytron claytron
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Martin Aspeli
On 04/13/2010 10:08 PM, Martin Aspeli wrote:

> On 14 April 2010 10:03, Alex Clark<[hidden email]>  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.

Clayton
--
[hidden email] | +1 (317) 861-5948 x603
six feet up presents INDIGO : The Help Line for Plone
More info at http://sixfeetup.com/indigo or call +1 (866) 749-3338



------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
--
six feet up, inc.  |  "Nowhere to go but open source"
Direct Line +1 (317) 861-5948 x603
clayton@sixfeetup.com
http://www.sixfeetup.com  |  Web publishing. Collaboration. Communities.

Dylan Jay-4 Dylan Jay-4
Reply | Threaded
Open this post in threaded view
|

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<[hidden email]>  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
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Anne Bowtell-3 Anne Bowtell-3
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by aclark
I think it would be helpful to have a more clearly managed approach with
someone in charge - Israel would be great, if he were prepared to take
up the challenge. It would be good also to have a more structured,
organized approach to sprinting on documentation too, so perhaps we
could entice some more people in to the process, by setting out some
more clearly defined tasks (rather like the trac tickets, but perhaps
with more detail and guidance)*.

I drafted a kind of 'vision' for core docs once - here's the link (I'm
running for cover):

http://docs.google.com/View?id=dfrk42sj_102c3xzjxdn

I'm more than aware that we need a documentation 'process' that we can
all join in to. I'm anxious because my day job is too demanding at the
moment and I can't spare the time to do much documentation, but there's
no one to pick up the reins.

Anne


* for instance I was able to get a group of colleagues to help with
screen-shots for the user manual, by giving them access to a Plone 4
instance (rather than asking them to install Plone 4 themselves)


On 14/04/2010 03:03, 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 :-).
>
> 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.
>
> Thoughts?
>
> Alex
>
>    

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

anne_bowtell.vcf (230 bytes) Download Attachment
aclark aclark
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Martin Aspeli
On 2010-04-14, Martin Aspeli <[hidden email]> wrote:
> +1000

Thanks for the enthusiastic reply :-)

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

That shouldn't be too hard. What's next, pitch to the PF?

> Martin
>
> ------------------------------------------------------------------------------
> 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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
aclark aclark
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by claytron
On 2010-04-14, Clayton Parker <[hidden email]> wrote:
> 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.

Don't forget the main point: to treat documentation as software i.e. version and release it.
This is key to motivation: working towards something e.g. a release.

>
> Clayton


--
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
aclark aclark
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Dylan Jay-4
On 2010-04-14, Dylan Jay <[hidden email]> wrote:
> whats in those couple of hours?

Working toward a release.

> I know the current/past?? organisation of the doc team has been around  
> "editors" and actually creating documentation, particularly now in the  
> manuals area. Is the suggestion that this new team be more about  
> making decisions rather than creating documentation?

Working toward a release. :-) It's really the same team with a more formal
structure and a target.

Dukebody, if "elected" becomes formal doc team leader, then doc team members
get selected, or elected, or whatever the FWT process is (which hannosch
has just promised to document).

> ------------------------------------------------------------------------------
> 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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Ricardo Newbery-2 Ricardo Newbery-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by aclark

+1

With the caveat that we should encourage a healthy rotation in the  
leader role similar to what happens right now in the FWT leader role.  
I also like the idea of syncing the doc release schedules more or less  
with the software release schedule.

Ric



On Apr 13, 2010, at 7:03 PM, 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 :-).
>
> 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.
>
> Thoughts?
>
> Alex
>
> --
> 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
> [hidden email]
> 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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Israel Saeta Pérez Israel Saeta Pérez
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by aclark
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Israel Saeta Pérez
Anne Bowtell-3 Anne Bowtell-3
Reply | Threaded
Open this post in threaded view
|

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


> 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.
I agree - plus we're running to keep up with core docs not yet finished
and Plone 4 around the corner.  Breaking things down into even smaller
parts would really help - as the scale of the task is sometimes
completely overwhelming and it can be hard to make progress.

Anne


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

anne_bowtell.vcf (168 bytes) Download Attachment
JoAnna Springsteen JoAnna Springsteen
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Israel Saeta Pérez
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.
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.


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
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
aclark aclark
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Anne Bowtell-3
On 2010-04-14, Anne Bowtell <[hidden email]> wrote:

> I think it would be helpful to have a more clearly managed approach with
> someone in charge - Israel would be great, if he were prepared to take
> up the challenge. It would be good also to have a more structured,
> organized approach to sprinting on documentation too, so perhaps we
> could entice some more people in to the process, by setting out some
> more clearly defined tasks (rather like the trac tickets, but perhaps
> with more detail and guidance)*.
>
> I drafted a kind of 'vision' for core docs once - here's the link (I'm
> running for cover):
>
> http://docs.google.com/View?id=dfrk42sj_102c3xzjxdn

This is great! No need to run for cover ;-)

> I'm more than aware that we need a documentation 'process' that we can
> all join in to. I'm anxious because my day job is too demanding at the
> moment and I can't spare the time to do much documentation, but there's
> no one to pick up the reins.
>
> Anne
>
>
> * for instance I was able to get a group of colleagues to help with
> screen-shots for the user manual, by giving them access to a Plone 4
> instance (rather than asking them to install Plone 4 themselves)
>
>
> On 14/04/2010 03:03, 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 :-).
>>
>> 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.
>>
>> Thoughts?
>>
>> Alex
>>
>>    
>
>
> --------------050607080705030508000105
> Content-Type: text/x-vcard; charset=utf-8;
>  name="anne_bowtell.vcf"
> Content-Transfer-Encoding: base64
> Content-Disposition: attachment;
>  filename="anne_bowtell.vcf"
>
> YmVnaW46dmNhcmQNCmZuOkFubmUgQm93dGVsbA0KbjpCb3d0ZWxsO0FubmUNCmVtYWlsO2lu
> dGVybmV0OmFubmUuYm93dGVsbEBtZWRzY2kub3guYWMudWsNCnRlbDt3b3JrOis0NCAoMCkx
> ODY1IDg4MjgyOQ0KeC1tb3ppbGxhLWh0bWw6RkFMU0UNCnZlcnNpb246Mi4xDQplbmQ6dmNh
> cmQNCg0K
> --------------050607080705030508000105
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
>
> ------------------------------------------------------------------------------
> 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
> --------------050607080705030508000105
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
>
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>
> --------------050607080705030508000105--
>
>


--
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Dylan Jay-4 Dylan Jay-4
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Israel Saeta Pérez
So whose job is it to prod those finishing the changes to the kb ui?
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 ;).

Dylan Jay
Technical solution manager
PretaWeb 99552830

On 15/04/2010, at 6:16 AM, Israel Saeta Pérez <[hidden email]>  
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
> [hidden email]
> 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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
claytron claytron
Reply | Threaded
Open this post in threaded view
|

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

On 04/14/2010 05:29 PM, Dylan Jay wrote:
> So whose job is it to prod those finishing the changes to the kb ui?
> 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.

+1, as mentioned time and again, the biggest issue is the time
commitment. We need someone to be the official cat herder!

> 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 ;).

That's a good point, I was thinking that the appointed/elected would
have to do the work. Either way we still need to make the day have more
hours in it ;)

Clayton
--
[hidden email] | +1 (317) 861-5948 x603
six feet up presents INDIGO : The Help Line for Plone
More info at http://sixfeetup.com/indigo or call +1 (866) 749-3338



> On 15/04/2010, at 6:16 AM, Israel Saeta Pérez<[hidden email]>
> 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
>> [hidden email]
>> 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
> [hidden email]
> 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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
--
six feet up, inc.  |  "Nowhere to go but open source"
Direct Line +1 (317) 861-5948 x603
clayton@sixfeetup.com
http://www.sixfeetup.com  |  Web publishing. Collaboration. Communities.

aclark aclark
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Dylan Jay-4
On 2010-04-14, Dylan Jay <[hidden email]> 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 <[hidden email]>  
> 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
>> [hidden email]
>> 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
> [hidden email]
> 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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
aclark aclark
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by JoAnna Springsteen
On 2010-04-14, JoAnna Springsteen <[hidden email]> 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".

> 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. ;-)

> 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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
aclark aclark
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Israel Saeta Pérez
On 2010-04-14, Israel Saeta Pérez <[hidden email]> wrote:
> I don't really know how to fight against the lack of motivation among
> the people working on documentation, including me.

Do you like getting paid? That is what I am proposing. I don't know
the likelyhood that the PF will buy into this, but it would seed
a lot of activity I think.

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

Me neither, and I hate stalls. Find a way to work around it, would be
my suggestion.

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

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.

This reads a bit dated to me, and in fact it says
    "This scheme will be replaced in a close future by manual owners. ".

How about this: With each release, the new doc team leader and members decide
    their roles, and accounce them to the community.

*shrug*

I don't know much about how this works within the FWT, just that
everyone owns something and collectively, eventually, their work
forms a release.

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

The most important thing I can think of is end-user documentation,
followed by "integrator" documentation. Developers, at least for now
can figure it out themselves ;-) (Well, not really but just trying to
prioritize).

Maybe installation docs, too.

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

Work towards a release. :-) There is only so much to be said about portlets
in a Plone 4 end user manual. The marketing peeps already cover "What's new?"
AFAIK.

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


--
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
123