Maintenance of Community Documentation

[Sebastian Ware]

Hi all,

I have had some discussions with Tim Cook and Steve Schmechel and we  
have agreed that we would like to put some effort into organising the  
maintenance of the community docs.

If we could get peoples blessing on this we would like to do the  
following:

-Create a separate Community Doc email list [grok-doc]
The purpose would be to highlight documentation efforts and questions  
related to documentation. This would be the place to go if one is  
working on community documentation or has questions related to  
community docs. This could also be the place where Grok users could  
learn more about the capabilities of Grok by reading the discussions.  
Basically we would like to support the emerging Grok culture of  
learning-by-writing-docs. This would benefit everybody.

-Organise a peer review workflow. Tagging content as:
  - Peer reviewed for version x.y (doc looks ok)
  - Out of date (with regards to current version)
  - Needs editing (for reason xyz)
  - Needs merging (with content xyz)

  Maybe create a simple webtool to keep track of peer reviews (if this  
isn't easily implemented in Plone).

-Organise on-line sprints every three months
The purpose is to focus the community during a week to peer review and  
improve community docs. If the tasks are reasonably well organised,  
this could be fun and very, very useful.

If this sounds reasonable I'll be happy to take a lead on this effort.

Mvh Sebastian
_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Sebastian Ware]

I just want to note that not getting an explicit go ahead is a show  
stopper for us. We need to know that we have the endorsement of the  
community in general and Martijn in particular.

Basically, if you think we are getting it wrong let us know so we  
don't waste everybodys time. And if you think we are getting it right,  
just give us a thumbs up.

Mvh Sebastian

8 jun 2009 kl. 10.31 skrev Sebastian Ware:

> Hi all,
>
> I have had some discussions with Tim Cook and Steve Schmechel and we
> have agreed that we would like to put some effort into organising the
> maintenance of the community docs.
>
> If we could get peoples blessing on this we would like to do the
> following:
>
> -Create a separate Community Doc email list [grok-doc]
> The purpose would be to highlight documentation efforts and questions
> related to documentation. This would be the place to go if one is
> working on community documentation or has questions related to
> community docs. This could also be the place where Grok users could
> learn more about the capabilities of Grok by reading the discussions.
> Basically we would like to support the emerging Grok culture of
> learning-by-writing-docs. This would benefit everybody.
>
> -Organise a peer review workflow. Tagging content as:
>  - Peer reviewed for version x.y (doc looks ok)
>  - Out of date (with regards to current version)
>  - Needs editing (for reason xyz)
>  - Needs merging (with content xyz)
>
>  Maybe create a simple webtool to keep track of peer reviews (if this
> isn't easily implemented in Plone).
>
> -Organise on-line sprints every three months
> The purpose is to focus the community during a week to peer review and
> improve community docs. If the tasks are reasonably well organised,
> this could be fun and very, very useful.
>
> If this sounds reasonable I'll be happy to take a lead on this effort.
>
> Mvh Sebastian
> _______________________________________________
> Grok-dev mailing list
> Grok-dev@...
> http://mail.zope.org/mailman/listinfo/grok-dev

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[wichert]

Previously Sebastian Ware wrote:
> I just want to note that not getting an explicit go ahead is a show  
> stopper for us. We need to know that we have the endorsement of the  
> community in general and Martijn in particular.
>
> Basically, if you think we are getting it wrong let us know so we  
> don't waste everybodys time. And if you think we are getting it right,  
> just give us a thumbs up.

+1

Wichert.

--
Wichert Akkerman <wichert@...>    It is simple to make things.
http://www.wiggy.net/                   It is hard to make things simple.
_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Uli Fouquet]

Hi there,

Sebastian Ware wrote:

> I have had some discussions with Tim Cook and Steve Schmechel and we  
> have agreed that we would like to put some effort into organising the  
> maintenance of the community docs.

Great :-)

> If we could get peoples blessing on this we would like to do the  
> following:
>
> -Create a separate Community Doc email list [grok-doc]
> The purpose would be to highlight documentation efforts and questions  
> related to documentation. This would be the place to go if one is  
> working on community documentation or has questions related to  
> community docs. This could also be the place where Grok users could  
> learn more about the capabilities of Grok by reading the discussions.  
> Basically we would like to support the emerging Grok culture of  
> learning-by-writing-docs. This would benefit everybody.

Do you think there would be so much traffic, that another list would be
required? Please note, that this list would also need maintenance and
people had to follow several lists then, especially when it comes to
technical (programming) details.

Therefore I am +0 for that.

From other people I learned, that they would like to see a grok-users
list, dedicated to mere beginner-like questions.

> -Organise a peer review workflow. Tagging content as:
>   - Peer reviewed for version x.y (doc looks ok)
>   - Out of date (with regards to current version)
>   - Needs editing (for reason xyz)
>   - Needs merging (with content xyz)
>
>   Maybe create a simple webtool to keep track of peer reviews (if this  
> isn't easily implemented in Plone).

If that would work: +1

> -Organise on-line sprints every three months
> The purpose is to focus the community during a week to peer review and  
> improve community docs. If the tasks are reasonably well organised,  
> this could be fun and very, very useful.

We should try this at least IMHO and see, how well it works. It's
certainly crucial that someone takes the initiative to organize the
whole stuff.

> If this sounds reasonable I'll be happy to take a lead on this effort.

Great, Sebastian, thanks! I'd propose, however, to have at least another
person (maybe Tim or Steve?) to share the workload and have a 'fallback'
contact ;-)

Overall: thank you very much for the effort. Sounds good to me :-)

Best regards,

--
Uli



_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Sebastian Ware]

9 jun 2009 kl. 10.34 skrev Uli Fouquet:

> Hi there,
>
> Sebastian Ware wrote:
>
>> I have had some discussions with Tim Cook and Steve Schmechel and we
>> have agreed that we would like to put some effort into organising the
>> maintenance of the community docs.
>
> Great :-)
>
>> If we could get peoples blessing on this we would like to do the
>> following:
>>
>> -Create a separate Community Doc email list [grok-doc]
>> The purpose would be to highlight documentation efforts and questions
>> related to documentation. This would be the place to go if one is
>> working on community documentation or has questions related to
>> community docs. This could also be the place where Grok users could
>> learn more about the capabilities of Grok by reading the discussions.
>> Basically we would like to support the emerging Grok culture of
>> learning-by-writing-docs. This would benefit everybody.
>
> Do you think there would be so much traffic, that another list would  
> be
> required? Please note, that this list would also need maintenance and
> people had to follow several lists then, especially when it comes to
> technical (programming) details.
>
> Therefore I am +0 for that.
>
> From other people I learned, that they would like to see a grok-users
> list, dedicated to mere beginner-like questions.

Actually, I think we should try to direct newbie questions to Stack  
Overflow

   http://stackoverflow.com/

It seems to be a really neat solution for this and it would improve  
Grok visibility. A mailing list usually hides answers in lengthy  
threads making it difficult and time consuming to untagle for a newbie.

>
>> -Organise a peer review workflow. Tagging content as:
>>  - Peer reviewed for version x.y (doc looks ok)
>>  - Out of date (with regards to current version)
>>  - Needs editing (for reason xyz)
>>  - Needs merging (with content xyz)
>>
>>  Maybe create a simple webtool to keep track of peer reviews (if this
>> isn't easily implemented in Plone).
>
> If that would work: +1
>
>> -Organise on-line sprints every three months
>> The purpose is to focus the community during a week to peer review  
>> and
>> improve community docs. If the tasks are reasonably well organised,
>> this could be fun and very, very useful.
>
> We should try this at least IMHO and see, how well it works. It's
> certainly crucial that someone takes the initiative to organize the
> whole stuff.
>
>> If this sounds reasonable I'll be happy to take a lead on this  
>> effort.
>
> Great, Sebastian, thanks! I'd propose, however, to have at least  
> another
> person (maybe Tim or Steve?) to share the workload and have a  
> 'fallback'
> contact ;-)

Haha... I know what you mean, I am counting on their support :)

>
> Overall: thank you very much for the effort. Sounds good to me :-)
>
> Best regards,
>
> --
> Uli
>

Mvh Sebastian



_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[ktenney]

On Tue, Jun 9, 2009 at 3:02 AM, Sebastian Ware<sebastian@...> wrote:
> I just want to note that not getting an explicit go ahead is a show
> stopper for us. We need to know that we have the endorsement of the
> community in general and Martijn in particular.
>
> Basically, if you think we are getting it wrong let us know so we
> don't waste everybodys time. And if you think we are getting it right,
> just give us a thumbs up.

+1

Thanks,
Kent

>
> Mvh Sebastian
>
> 8 jun 2009 kl. 10.31 skrev Sebastian Ware:
>
>> Hi all,
>>
>> I have had some discussions with Tim Cook and Steve Schmechel and we
>> have agreed that we would like to put some effort into organising the
>> maintenance of the community docs.
>>
>> If we could get peoples blessing on this we would like to do the
>> following:
>>
>> -Create a separate Community Doc email list [grok-doc]
>> The purpose would be to highlight documentation efforts and questions
>> related to documentation. This would be the place to go if one is
>> working on community documentation or has questions related to
>> community docs. This could also be the place where Grok users could
>> learn more about the capabilities of Grok by reading the discussions.
>> Basically we would like to support the emerging Grok culture of
>> learning-by-writing-docs. This would benefit everybody.
>>
>> -Organise a peer review workflow. Tagging content as:
>>  - Peer reviewed for version x.y (doc looks ok)
>>  - Out of date (with regards to current version)
>>  - Needs editing (for reason xyz)
>>  - Needs merging (with content xyz)
>>
>>  Maybe create a simple webtool to keep track of peer reviews (if this
>> isn't easily implemented in Plone).
>>
>> -Organise on-line sprints every three months
>> The purpose is to focus the community during a week to peer review and
>> improve community docs. If the tasks are reasonably well organised,
>> this could be fun and very, very useful.
>>
>> If this sounds reasonable I'll be happy to take a lead on this effort.
>>
>> Mvh Sebastian
>> _______________________________________________
>> Grok-dev mailing list
>> Grok-dev@...
>> http://mail.zope.org/mailman/listinfo/grok-dev
>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev@...
> http://mail.zope.org/mailman/listinfo/grok-dev
>

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Martijn Faassen-2]

Hey Sebastian,

Sorry I haven't been paying enough attention in the last week. :)

Sebastian Ware wrote:
> -Create a separate Community Doc email list [grok-doc]
> The purpose would be to highlight documentation efforts and questions  
> related to documentation. This would be the place to go if one is  
> working on community documentation or has questions related to  
> community docs. This could also be the place where Grok users could  
> learn more about the capabilities of Grok by reading the discussions.  
> Basically we would like to support the emerging Grok culture of  
> learning-by-writing-docs. This would benefit everybody.

I'm -0 to a new mailing list; I don't think grok-dev is very high
traffic and having the discussions taking place on a single mailing list
might encourage more people to contribute.

You mention also that a grok-doc mailing list might be useful for users.
It's interesting that there'd be a -doc list before a -users list then.
(I'm -0 to any new lists at this stage though).

If people really do want a new mailing list I can see about having it
created on zope.org.

> -Organise a peer review workflow. Tagging content as:
>   - Peer reviewed for version x.y (doc looks ok)
>   - Out of date (with regards to current version)
>   - Needs editing (for reason xyz)
>   - Needs merging (with content xyz)
>
>   Maybe create a simple webtool to keep track of peer reviews (if this  
> isn't easily implemented in Plone).

+1 on such a workflow!

I'd suggest trying to come up with a workflow "on paper" and following
that for a while before worrying about codifying it in software. This
way the focus will be on improving the documentation instead of writing
software.

> -Organise on-line sprints every three months
> The purpose is to focus the community during a week to peer review and  
> improve community docs. If the tasks are reasonably well organised,  
> this could be fun and very, very useful.
>
> If this sounds reasonable I'll be happy to take a lead on this effort.

I'm very happy to see you take this initiative, Sebastian!

Regards,

P.S. I know I've been somewhat absent here for a while, but I expect to
spend some more time on Grok related issues in the future.

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev