Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Gentoo: Doc

Review of Documentation Policy

 

 

Gentoo doc RSS feed   Index | Next | Previous | View Threaded


swift at gentoo

Aug 15, 2011, 2:23 PM

Post #1 of 21 (2241 views)
Permalink
Review of Documentation Policy

Hi guys,

Sorry to barge in like this here, but why not start a nice discussion on
things... Keeps the minds fresh and the activity high (heh, almost sounds
like a bad exercise DVD).

The GDP currently uses the Documentation Policy [1] as its main policy on
documentation development, recruitment, team organization and what not. It
was written a few years ago and has seen some small changes since. However,
like any policy, it should best be reviewed from time to time.

So, what is your take on the policy? Which things need to be changed? What
would you like to see added?

Wkr,
Sven Vermeulen

[1] http://www.gentoo.org/proj/en/gdp/doc/doc-policy.xml


mattst88 at gentoo

Aug 15, 2011, 2:46 PM

Post #2 of 21 (2151 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Mon, Aug 15, 2011 at 5:23 PM, Sven Vermeulen <swift [at] gentoo> wrote:
> Hi guys,
>
> Sorry to barge in like this here, but why not start a nice discussion on
> things... Keeps the minds fresh and the activity high (heh, almost sounds
> like a bad exercise DVD).
>
> The GDP currently uses the Documentation Policy [1] as its main policy on
> documentation development, recruitment, team organization and what not. It
> was written a few years ago and has seen some small changes since. However,
> like any policy, it should best be reviewed from time to time.
>
> So, what is your take on the policy? Which things need to be changed? What
> would you like to see added?
>
> Wkr,
> Sven Vermeulen
>
> [1] http://www.gentoo.org/proj/en/gdp/doc/doc-policy.xml

The recruiting information seems strange and unnecessarily structured.
It all seems to be written for people who are not developers.

The Contributions phase mentions a lot of undefined titles,
"Operational Manager", "Full-time Developer", "Part-time Developer".
There's a table that shows the number of contributions/time for a
developer, but what do these roles actually mean? Who/what is an
"Operational Manager"?

> ... to inform the contributor about the time-consuming position and pressure the application involves.

Come on. What is this? I don't think I remember getting paid as a
Gentoo developer. This nonsense about time commitments and pressure is
pretentious.

It seems to me that the steps for joining the Docs team for a current
developer should be much more clearly stated.

Thanks,
Matt


mattst88 at gentoo

Aug 15, 2011, 2:46 PM

Post #3 of 21 (2152 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Mon, Aug 15, 2011 at 5:23 PM, Sven Vermeulen <swift [at] gentoo> wrote:
> Hi guys,
>
> Sorry to barge in like this here, but why not start a nice discussion on
> things... Keeps the minds fresh and the activity high (heh, almost sounds
> like a bad exercise DVD).
>
> The GDP currently uses the Documentation Policy [1] as its main policy on
> documentation development, recruitment, team organization and what not. It
> was written a few years ago and has seen some small changes since. However,
> like any policy, it should best be reviewed from time to time.
>
> So, what is your take on the policy? Which things need to be changed? What
> would you like to see added?
>
> Wkr,
> Sven Vermeulen
>
> [1] http://www.gentoo.org/proj/en/gdp/doc/doc-policy.xml

The recruiting information seems strange and unnecessarily structured.
It all seems to be written for people who are not developers.

The Contributions phase mentions a lot of undefined titles,
"Operational Manager", "Full-time Developer", "Part-time Developer".
There's a table that shows the number of contributions/time for a
developer, but what do these roles actually mean? Who/what is an
"Operational Manager"?

> ... to inform the contributor about the time-consuming position and pressure the application involves.

Come on. What is this? I don't think I remember getting paid as a
Gentoo developer. This nonsense about time commitments and pressure is
pretentious.

It seems to me that the steps for joining the Docs team for a current
developer should be much more clearly stated.

Thanks,
Matt


swift at gentoo

Aug 19, 2011, 10:22 AM

Post #4 of 21 (2165 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Mon, Aug 15, 2011 at 05:46:01PM -0400, Matt Turner wrote:
> The recruiting information seems strange and unnecessarily structured.
> It all seems to be written for people who are not developers.
>
> The Contributions phase mentions a lot of undefined titles,
> "Operational Manager", "Full-time Developer", "Part-time Developer".
> There's a table that shows the number of contributions/time for a
> developer, but what do these roles actually mean? Who/what is an
> "Operational Manager"?

That's "old school" and is indeed something that we ought to improve in the
description.

> > ... to inform the contributor about the time-consuming position and pressure the application involves.
>
> Come on. What is this? I don't think I remember getting paid as a
> Gentoo developer. This nonsense about time commitments and pressure is
> pretentious.
>
> It seems to me that the steps for joining the Docs team for a current
> developer should be much more clearly stated.

Any suggestion here? It isn't difficult to update the policy to be more
real-life like (my own immediate suggestion would be to drop the "numbered"
commit / bug requirement and instead use a regular mentoring role, and
putting the responsibility of acknowledging in the mentor's lap) but we
might even go beyond just "updating" the policy.

Let's take a fresh look and see ;-)

Wkr,
Sven Vermeulen


mattst88 at gentoo

Aug 22, 2011, 5:16 PM

Post #5 of 21 (2129 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Fri, Aug 19, 2011 at 1:22 PM, Sven Vermeulen <swift [at] gentoo> wrote:
>> > ... to inform the contributor about the time-consuming position and pressure the application involves.
>>
>> Come on. What is this? I don't think I remember getting paid as a
>> Gentoo developer. This nonsense about time commitments and pressure is
>> pretentious.
>>
>> It seems to me that the steps for joining the Docs team for a current
>> developer should be much more clearly stated.
>
> Any suggestion here? It isn't difficult to update the policy to be more
> real-life like (my own immediate suggestion would be to drop the "numbered"
> commit / bug requirement and instead use a regular mentoring role, and
> putting the responsibility of acknowledging in the mentor's lap) but we
> might even go beyond just "updating" the policy.

The information on this page is very irrelevant and confusing to me,
as a developer.

I don't know how many non-developer documenters we have. I don't know
what needs to happen to that text itself, but a section about how
current developers join the documentation team is important. Looking
at the page, a person must complete the staff and doc quizzes. For a
developer, it seems that the requirements should simply be 1) to have
become a developer and 2) completed the doc quiz.

Thanks,
Matt


swift at gentoo

Aug 23, 2011, 1:52 AM

Post #6 of 21 (2131 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Mon, Aug 22, 2011 at 08:16:59PM -0400, Matt Turner wrote:
> The information on this page is very irrelevant and confusing to me,
> as a developer.
>
> I don't know how many non-developer documenters we have. I don't know
> what needs to happen to that text itself, but a section about how
> current developers join the documentation team is important. Looking
> at the page, a person must complete the staff and doc quizzes. For a
> developer, it seems that the requirements should simply be 1) to have
> become a developer and 2) completed the doc quiz.

Documentation developers are also developers, but they do not need to be an
ebuild-developer. If I look at the GDP current staffing, there are 8
developers that are also ebuild developers (or infrastructure or another
function within Gentoo) and 11 developers on the documentation (and
translations) only.

Requiring documentation developers to also take the ebuild and end quiz
would be overshooting, as that is not something they require.

Wkr,
Sven Vermeulen


mattst88 at gentoo

Aug 23, 2011, 6:43 AM

Post #7 of 21 (2124 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <swift [at] gentoo> wrote:
> On Mon, Aug 22, 2011 at 08:16:59PM -0400, Matt Turner wrote:
>> The information on this page is very irrelevant and confusing to me,
>> as a developer.
>>
>> I don't know how many non-developer documenters we have. I don't know
>> what needs to happen to that text itself, but a section about how
>> current developers join the documentation team is important. Looking
>> at the page, a person must complete the staff and doc quizzes. For a
>> developer, it seems that the requirements should simply be 1) to have
>> become a developer and 2) completed the doc quiz.
>
> Documentation developers are also developers, but they do not need to be an
> ebuild-developer. If I look at the GDP current staffing, there are 8
> developers that are also ebuild developers (or infrastructure or another
> function within Gentoo) and 11 developers on the documentation (and
> translations) only.
>
> Requiring documentation developers to also take the ebuild and end quiz
> would be overshooting, as that is not something they require.
>
> Wkr,
> Sven Vermeulen

Right, I'm saying for people who are already developers, they should
really only have to complete the doc quiz.

Matt


nightmorph at gentoo

Aug 24, 2011, 10:41 PM

Post #8 of 21 (2112 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Tue, 23 Aug 2011 09:43:51 -0400
Matt Turner <mattst88 [at] gentoo> wrote:

> On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <swift [at] gentoo>
> wrote:
> > On Mon, Aug 22, 2011 at 08:16:59PM -0400, Matt Turner wrote:
> >> The information on this page is very irrelevant and confusing to
> >> me, as a developer.
> >>
> >> I don't know how many non-developer documenters we have. I don't
> >> know what needs to happen to that text itself, but a section
> >> about how current developers join the documentation team is
> >> important. Looking at the page, a person must complete the staff
> >> and doc quizzes. For a developer, it seems that the requirements
> >> should simply be 1) to have become a developer and 2) completed
> >> the doc quiz.
> >
> > Documentation developers are also developers, but they do not
> > need to be an ebuild-developer. If I look at the GDP current
> > staffing, there are 8 developers that are also ebuild developers
> > (or infrastructure or another function within Gentoo) and 11
> > developers on the documentation (and translations) only.
> >
> > Requiring documentation developers to also take the ebuild and
> > end quiz would be overshooting, as that is not something they
> > require.
> >
> > Wkr,
> >        Sven Vermeulen
>
> Right, I'm saying for people who are already developers, they should
> really only have to complete the doc quiz.
>
> Matt
>

You want to contribute ebuilds, you have to go through a process that
teaches you what you need to know, and shows your mentor that know
what you're doing; that you're not going to screw up everyone's
boxes.

You want to write documentation, you have to go through a process
that teaches you what you need to know, and shows your mentor that
you know what you're doing; that you're not going to screw up
everyone's boxes ... *or the Gentoo websites*. (via bad commits that
break layouts, links, XML, CSS, etc.)

Everyone has to go through a process when wanting to join a team.
What's so hard about this? Why should ebuild developers get a free
pass to get write access? Over the years, I've talked with several
different ebuild team leads, as I was interested in what it took to
get access to gentoo-x86. There's no free pass for longtime doc
writers, either, even those that have run their own private overlay
for a long time. I don't just take the ebuild quiz and get commit
access. There's a process that I have to go through, too.

Maybe I'm just reading this wrong, but it sounds like you want to set
things up so that anyone who wants to change a doc can overwrite it
directly. That's fine for stuff in /proj/ -- the GDP doesn't care
about that; documents in /proj/ are solely the responsibility of those
projects. And that's why, overall, the quality of stuff in /proj/ is
not as good as what's in /doc/.
Attachments: signature.asc (0.19 KB)


mattst88 at gentoo

Aug 25, 2011, 7:45 PM

Post #9 of 21 (2107 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Thu, Aug 25, 2011 at 1:41 AM, Joshua Saddler <nightmorph [at] gentoo> wrote:
> On Tue, 23 Aug 2011 09:43:51 -0400
> Matt Turner <mattst88 [at] gentoo> wrote:
>
>> On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <swift [at] gentoo>
>> wrote:
>> > On Mon, Aug 22, 2011 at 08:16:59PM -0400, Matt Turner wrote:
>> >> The information on this page is very irrelevant and confusing to
>> >> me, as a developer.
>> >>
>> >> I don't know how many non-developer documenters we have. I don't
>> >> know what needs to happen to that text itself, but a section
>> >> about how current developers join the documentation team is
>> >> important. Looking at the page, a person must complete the staff
>> >> and doc quizzes. For a developer, it seems that the requirements
>> >> should simply be 1) to have become a developer and 2) completed
>> >> the doc quiz.
>> >
>> > Documentation developers are also developers, but they do not
>> > need to be an ebuild-developer. If I look at the GDP current
>> > staffing, there are 8 developers that are also ebuild developers
>> > (or infrastructure or another function within Gentoo) and 11
>> > developers on the documentation (and translations) only.
>> >
>> > Requiring documentation developers to also take the ebuild and
>> > end quiz would be overshooting, as that is not something they
>> > require.
>> >
>> > Wkr,
>> > Sven Vermeulen
>>
>> Right, I'm saying for people who are already developers, they should
>> really only have to complete the doc quiz.
>>
>> Matt
>>
>
> You want to contribute ebuilds, you have to go through a process that
> teaches you what you need to know, and shows your mentor that know
> what you're doing; that you're not going to screw up everyone's
> boxes.
>
> You want to write documentation, you have to go through a process
> that teaches you what you need to know, and shows your mentor that
> you know what you're doing; that you're not going to screw up
> everyone's boxes ... *or the Gentoo websites*. (via bad commits that
> break layouts, links, XML, CSS, etc.)
>
> Everyone has to go through a process when wanting to join a team.
> What's so hard about this? Why should ebuild developers get a free
> pass to get write access? Over the years, I've talked with several
> different ebuild team leads, as I was interested in what it took to
> get access to gentoo-x86. There's no free pass for longtime doc
> writers, either, even those that have run their own private overlay
> for a long time. I don't just take the ebuild quiz and get commit
> access. There's a process that I have to go through, too.
>
> Maybe I'm just reading this wrong, but it sounds like you want to set
> things up so that anyone who wants to change a doc can overwrite it
> directly. That's fine for stuff in /proj/ -- the GDP doesn't care
> about that; documents in /proj/ are solely the responsibility of those
> projects. And that's why, overall, the quality of stuff in /proj/ is
> not as good as what's in /doc/.

I appear to have touched a nerve.

Let me revise my previous email. I think an existing (ebuild)
developer should do the following things to join the doc team:
- doc quiz;
- CSS knowledge is a plus;
- have some documentation patches to prove he's not a doofus.

I don't intend to belittle the doc team, but while your point about
having to go through mentoring for an ebuild developer and therefore
why not also a doc developer is well taken, I have a hard time
believing that there's nearly as much knowledge to take in to become a
documentation developer. Learning GuideXML can be done in a day or
two. Being a good writer is something not easily learned.

But whatever. I'll just post patches in bug reports. It's not worth
the time to go through a second recruitment process to that I can
modify a couple pieces of documentation about the architecture teams
I'm a member of. Maybe these documents should be under /proj anyway;
they certainly weren't looking very healthy under /doc.

Matt


klondike at gentoo

Aug 31, 2011, 2:59 PM

Post #10 of 21 (2054 views)
Permalink
Re: Review of Documentation Policy [In reply to]

El 26/08/11 04:45, Matt Turner escribi:
> On Thu, Aug 25, 2011 at 1:41 AM, Joshua Saddler <nightmorph [at] gentoo> wrote:
>> On Tue, 23 Aug 2011 09:43:51 -0400
>> Matt Turner <mattst88 [at] gentoo> wrote:
>>
>>> On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <swift [at] gentoo>
>>> wrote:
>>>> On Mon, Aug 22, 2011 at 08:16:59PM -0400, Matt Turner wrote:
>>>>> The information on this page is very irrelevant and confusing to
>>>>> me, as a developer.
>>>>>
>>>>> I don't know how many non-developer documenters we have. I don't
>>>>> know what needs to happen to that text itself, but a section
>>>>> about how current developers join the documentation team is
>>>>> important. Looking at the page, a person must complete the staff
>>>>> and doc quizzes. For a developer, it seems that the requirements
>>>>> should simply be 1) to have become a developer and 2) completed
>>>>> the doc quiz.
>>>> Documentation developers are also developers, but they do not
>>>> need to be an ebuild-developer. If I look at the GDP current
>>>> staffing, there are 8 developers that are also ebuild developers
>>>> (or infrastructure or another function within Gentoo) and 11
>>>> developers on the documentation (and translations) only.
>>>>
>>>> Requiring documentation developers to also take the ebuild and
>>>> end quiz would be overshooting, as that is not something they
>>>> require.
>>>>
>>>> Wkr,
>>>> Sven Vermeulen
>>> Right, I'm saying for people who are already developers, they should
>>> really only have to complete the doc quiz.
>>>
>>> Matt
>>>
>> You want to contribute ebuilds, you have to go through a process that
>> teaches you what you need to know, and shows your mentor that know
>> what you're doing; that you're not going to screw up everyone's
>> boxes.
>>
>> You want to write documentation, you have to go through a process
>> that teaches you what you need to know, and shows your mentor that
>> you know what you're doing; that you're not going to screw up
>> everyone's boxes ... *or the Gentoo websites*. (via bad commits that
>> break layouts, links, XML, CSS, etc.)
>>
>> Everyone has to go through a process when wanting to join a team.
>> What's so hard about this? Why should ebuild developers get a free
>> pass to get write access? Over the years, I've talked with several
>> different ebuild team leads, as I was interested in what it took to
>> get access to gentoo-x86. There's no free pass for longtime doc
>> writers, either, even those that have run their own private overlay
>> for a long time. I don't just take the ebuild quiz and get commit
>> access. There's a process that I have to go through, too.
Yeah but if it is a big nuissance people won't go through it.
>> Maybe I'm just reading this wrong, but it sounds like you want to set
>> things up so that anyone who wants to change a doc can overwrite it
>> directly. That's fine for stuff in /proj/ -- the GDP doesn't care
>> about that; documents in /proj/ are solely the responsibility of those
>> projects. And that's why, overall, the quality of stuff in /proj/ is
>> not as good as what's in /doc/.
Maybe that's why proj tends to be more up to date than doc or why we
still have the openrc tracker bug open whith many bugs just requiring
minor changes to be fixed.
> I appear to have touched a nerve.
>
> Let me revise my previous email. I think an existing (ebuild)
> developer should do the following things to join the doc team:
> - doc quiz;
> - CSS knowledge is a plus;
> - have some documentation patches to prove he's not a doofus.
>
> I don't intend to belittle the doc team, but while your point about
> having to go through mentoring for an ebuild developer and therefore
> why not also a doc developer is well taken, I have a hard time
> believing that there's nearly as much knowledge to take in to become a
> documentation developer. Learning GuideXML can be done in a day or
> two. Being a good writer is something not easily learned.
Gonna rephrase that if you don't mind:
I don't intend to belittle the ebuild writers, but while your point about
having to go through mentoring for an ebuild developer and therefore
why not also a doc developer is well taken, I have a hard time
believing that there's nearly as much knowledge to take in to become an
ebuild developer. Learning to write ebuilds can be done in a day or
two. Being a good writer is something not easily learned.

That said I have already written ebuilds which work but... Oh! I'm not a full developer because I have yet to pass the quizzes (which I hope I'll eventually do).

> But whatever. I'll just post patches in bug reports. It's not worth
> the time to go through a second recruitment process to that I can
> modify a couple pieces of documentation about the architecture teams
> I'm a member of. Maybe these documents should be under /proj anyway;
> they certainly weren't looking very healthy under /doc.
That's what I usually do and then have fun seeing them ignored by the
package responsibles... For example I'm still waiting for news of the
dev-p2p team on an updated linuxdcpp ebuild with some patches I sent in
July.

So where I'm trying to get?

Well turns out both sides have bad practices but whilst one is
overpopulated the other one isn't. My opinion is that the best policy
would be a segmentated policy (as for example happens with staffer and
full developers), and have two types of document writters ones which
only do a small test and only correct small thingies, and the ones that
do the long test to be able to do major changes and write docs from
scratch. Both should be surveilled for some time (basically until the
newbie does things properly) by somebody with experience who should tell
them what to fix (because yes, at times there is nothing better to avoid
mistakes than being shown them).

What we'd get from that in the middle term will be a doc team with a
large base of small fixers which keep documents up to date and some big
guys that will produce new quality documentation.

Those are just my 2 cents.
Attachments: signature.asc (0.26 KB)


swift at gentoo

Sep 23, 2011, 12:49 PM

Post #11 of 21 (1993 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Tue, Aug 23, 2011 at 08:52:46AM +0000, Sven Vermeulen wrote:
> Documentation developers are also developers, but they do not need to be an
> ebuild-developer. If I look at the GDP current staffing, there are 8
> developers that are also ebuild developers (or infrastructure or another
> function within Gentoo) and 11 developers on the documentation (and
> translations) only.
>
> Requiring documentation developers to also take the ebuild and end quiz
> would be overshooting, as that is not something they require.

Okay, I have a suggestion for the Gentoo Documentation Project Policy. The
suggested document can be found at [1], the diff output at [2].

[1] http://dev.gentoo.org/~swift/docs/previews/doc-policy.xml
[2] http://dev.gentoo.org/~swift/docs/previews/doc-policy.txt

Feedback is, as always, very much appreciated. Joshua, especially from you
(I definitely do not want to touch that guide without your blessing ;-)

Wkr,
Sven Vermeulen


nightmorph at gentoo

Sep 23, 2011, 5:22 PM

Post #12 of 21 (1987 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Fri, 23 Sep 2011 19:49:25 +0000
Sven Vermeulen <swift [at] gentoo> wrote:

> Okay, I have a suggestion for the Gentoo Documentation Project
> Policy. The suggested document can be found at [1], the diff output
> at [2].
>
> [1] http://dev.gentoo.org/~swift/docs/previews/doc-policy.xml
> [2] http://dev.gentoo.org/~swift/docs/previews/doc-policy.txt
>
> Feedback is, as always, very much appreciated. Joshua, especially
> from you (I definitely do not want to touch that guide without your
> blessing ;-)

Thanks for the draft! From a quick run-through of the patch (much
obliged for that, thanks), it seems pretty good.

The major differences to the original doc are:

1. Doing away with the Strategic/Operational lead split. We haven't
had two people doing those jobs in 5 years, anyway.

2. Translation project leads and "official" language status. Any
comments as to the changes here?

3. Join-up process. No formal "X number of contributions per period
Y." Works well enough for me, but then "how much does this potential
recruit actually do for us" becomes subjective hand-waving. We would
need a new metric to determine commitment over time. Ideas?

Anyway, if you can clarify your thinking on these 3 points, just so I
know where you're coming from, I'm fine with the proposed update.

How about the other GDP members -- any thoughts from the rest of you?
Attachments: signature.asc (0.19 KB)


swift at gentoo

Sep 23, 2011, 11:39 PM

Post #13 of 21 (1984 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Fri, Sep 23, 2011 at 05:22:37PM -0700, Joshua Saddler wrote:
> Thanks for the draft! From a quick run-through of the patch (much
> obliged for that, thanks), it seems pretty good.
>
> The major differences to the original doc are:
>
> 1. Doing away with the Strategic/Operational lead split. We haven't
> had two people doing those jobs in 5 years, anyway.

Yup, most - if not all - other projects are based on a project lead and lots
of minions, so this was a fairly obvious change imo.

> 2. Translation project leads and "official" language status. Any
> comments as to the changes here?

Sure. I wanted to make it a bit less formal without lowering the
requirements. Now, the document sais that a language should be backed up by
a translation team where at least one member (the translation project lead)
has commit access. If this isn't the case, then it is an "unsupported" language
where the documents are still published, but not linked.

> 3. Join-up process. No formal "X number of contributions per period
> Y." Works well enough for me, but then "how much does this potential
> recruit actually do for us" becomes subjective hand-waving. We would
> need a new metric to determine commitment over time. Ideas?

I'm not sure we need one. Imo, the GDP project lead decides when phase 2
starts (and as such when a mentor is assigned). From then onwards, it is the
mentor who is in charge of defining when the recruitment can be started.

If we need a more objective metric to start with, I'd rather do it on
timeframe ("... sufficient document changes over a term of at least 4
months"), which holds twice then (first and second phase).

After all, developers that have been less or inactive for some time are
slated to be retired anyhow, either fully (from the Gentoo project) or from
the GDP (removal of the GDP page and perhaps cvsdoc commit rights).

Wkr,
Sven Vermeulen


nightmorph at gentoo

Sep 24, 2011, 6:22 PM

Post #14 of 21 (1974 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Sat, 24 Sep 2011 08:39:41 +0200
Sven Vermeulen <swift [at] gentoo> wrote:

> > 2. Translation project leads and "official" language status. Any
> > comments as to the changes here?
>
> Sure. I wanted to make it a bit less formal without lowering the
> requirements. Now, the document sais that a language should be
> backed up by a translation team where at least one member (the
> translation project lead) has commit access. If this isn't the
> case, then it is an "unsupported" language where the documents are
> still published, but not linked.

Fine with me; I assume the translators are okay with this, too.

> > 3. Join-up process. No formal "X number of contributions per
> > period Y." Works well enough for me, but then "how much does this
> > potential recruit actually do for us" becomes subjective
> > hand-waving. We would need a new metric to determine commitment
> > over time. Ideas?
>
> I'm not sure we need one. Imo, the GDP project lead decides when
> phase 2 starts (and as such when a mentor is assigned). From then
> onwards, it is the mentor who is in charge of defining when the
> recruitment can be started.
>
> If we need a more objective metric to start with, I'd rather do it
> on timeframe ("... sufficient document changes over a term of at
> least 4 months"), which holds twice then (first and second phase).
>
> After all, developers that have been less or inactive for some time
> are slated to be retired anyhow, either fully (from the Gentoo
> project) or from the GDP (removal of the GDP page and perhaps
> cvsdoc commit rights).

This makes sense.

Alright, commit the thing. I like it.
Attachments: signature.asc (0.19 KB)


nimiux at gentoo

Sep 25, 2011, 11:41 AM

Post #15 of 21 (1976 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Sat, Sep 24, 2011 at 06:22:34PM -0700, Joshua Saddler wrote:
> On Sat, 24 Sep 2011 08:39:41 +0200
> Sven Vermeulen <swift [at] gentoo> wrote:
>
> > > 2. Translation project leads and "official" language status. Any
> > > comments as to the changes here?
> >
> > Sure. I wanted to make it a bit less formal without lowering the
> > requirements. Now, the document sais that a language should be
> > backed up by a translation team where at least one member (the
> > translation project lead) has commit access. If this isn't the
> > case, then it is an "unsupported" language where the documents are
> > still published, but not linked.
>
> Fine with me; I assume the translators are okay with this, too.
>

Ok with this. The draft looks fine to me.

Thanks!

> > > 3. Join-up process. No formal "X number of contributions per
> > > period Y." Works well enough for me, but then "how much does this
> > > potential recruit actually do for us" becomes subjective
> > > hand-waving. We would need a new metric to determine commitment
> > > over time. Ideas?
> >
> > I'm not sure we need one. Imo, the GDP project lead decides when
> > phase 2 starts (and as such when a mentor is assigned). From then
> > onwards, it is the mentor who is in charge of defining when the
> > recruitment can be started.
> >
> > If we need a more objective metric to start with, I'd rather do it
> > on timeframe ("... sufficient document changes over a term of at
> > least 4 months"), which holds twice then (first and second phase).
> >
> > After all, developers that have been less or inactive for some time
> > are slated to be retired anyhow, either fully (from the Gentoo
> > project) or from the GDP (removal of the GDP page and perhaps
> > cvsdoc commit rights).
>
> This makes sense.
>
> Alright, commit the thing. I like it.


swift at gentoo

Sep 27, 2011, 11:05 AM

Post #16 of 21 (1969 views)
Permalink
Re: Review of Documentation Policy [In reply to]

Thank you all for reviewing. I've committed the document in CVS.

Wkr,
Sven Vermeulen


cam at gentoo

Sep 28, 2011, 7:49 AM

Post #17 of 21 (1950 views)
Permalink
Re: Review of Documentation Policy [In reply to]

Hey, sorry for my late feedback,

"""
The Gentoo Documentation Project Team consists of editors and authors,
working
on our main documentation and its translations. Like most other Gentoo
projects,
it is lead by a project lead whose additional job is to look after the team
and
its resources in general (such as focusing on recruitment when necessary and
acting as an unbiased mediator when two or more developers have a dispute
over
something).
"""

I don't like the end "acting as an unbiased mediator when two or more
developers have a dispute over
something", we're not childs that need to be calm down :) -- Here's my
suggested drop-in: "taking final decisions when consensus cannot be found
otherwise."

(I also spotted a typo: it is lead -> it is led)

I can commit the changes if you're fine.

Best,
Camille Huot


sven.vermeulen at siphos

Sep 28, 2011, 11:13 AM

Post #18 of 21 (1956 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Wed, Sep 28, 2011 at 04:49:53PM +0200, Camille Huot wrote:
> Hey, sorry for my late feedback,

No problem.

> """
> The Gentoo Documentation Project Team consists of editors and authors,
> working
> on our main documentation and its translations. Like most other Gentoo
> projects,
> it is lead by a project lead whose additional job is to look after the team
> and
> its resources in general (such as focusing on recruitment when necessary and
> acting as an unbiased mediator when two or more developers have a dispute
> over
> something).
> """
>
> I don't like the end "acting as an unbiased mediator when two or more
> developers have a dispute over
> something", we're not childs that need to be calm down :) -- Here's my
> suggested drop-in: "taking final decisions when consensus cannot be found
> otherwise."

Actually, I was merely trying to replicate what the devrel stuff sais on
this ;-) It isn't about a dispute on documentation aspects. If that were the
case, I'd suggest a "consensus model" on the mailinglist and indeed project
lead having a final say if consensus cannot be found.

But when developers are more in dispute on non-documentation related
aspects, the devrel guide/policy currently positions the project lead as a
first mediator.

Of course, we could just drop that part (since it already is in the policy)
or rewrite it according to your suggestion (but then make it clear it is
about project-related activities).

Wkr,
Sven Vermeulen


klondike at gentoo

Sep 28, 2011, 11:32 AM

Post #19 of 21 (1947 views)
Permalink
Re: Review of Documentation Policy [In reply to]

El 24/09/11 08:39, Sven Vermeulen escribió:
> If we need a more objective metric to start with, I'd rather do it on
> timeframe ("... sufficient document changes over a term of at least 4
> months"), which holds twice then (first and second phase)
It may be me but I'm still wondering why do you need an objective
metric. Usually the project lead should be smart enough to know when to
pull the rope and accept into the team a particular colaborator.
Attachments: signature.asc (0.26 KB)


quantumsummers at gentoo

Sep 28, 2011, 11:36 AM

Post #20 of 21 (1955 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Wed, Sep 28, 2011 at 1:32 PM, Francisco Blas Izquierdo Riera (klondike) <
klondike [at] gentoo> wrote:

> El 24/09/11 08:39, Sven Vermeulen escribió:
> > If we need a more objective metric to start with, I'd rather do it on
> > timeframe ("... sufficient document changes over a term of at least 4
> > months"), which holds twice then (first and second phase)
> It may be me but I'm still wondering why do you need an objective
> metric. Usually the project lead should be smart enough to know when to
> pull the rope and accept into the team a particular colaborator.
>
>
Checks and balances, my friend, checks and balances. I would be more
concerned about the lead _refusing_ the contrib or entry into the project of
a particular individual.

Cheerio
--
Matthew W. Summers
Gentoo Foundation Inc.


titanofold at gentoo

Sep 28, 2011, 11:45 AM

Post #21 of 21 (1948 views)
Permalink
Re: Review of Documentation Policy [In reply to]

On Wed, Sep 28, 2011 at 08:13:00PM +0200, Sven Vermeulen wrote:
> On Wed, Sep 28, 2011 at 04:49:53PM +0200, Camille Huot wrote:
> > Hey, sorry for my late feedback,
>
> No problem.
>
> > """
> > The Gentoo Documentation Project Team consists of editors and authors,
> > working on our main documentation and its translations. Like most other
> > Gentoo projects, it is lead by a project lead whose additional job is to
> > look after the team and its resources in general (such as focusing on
> > recruitment when necessary and acting as an unbiased mediator when two or
> > more developers have a dispute over something).
> > """
> >
> > I don't like the end "acting as an unbiased mediator when two or more
> > developers have a dispute over something", we're not childs that need to be
> > calm down :) -- Here's my suggested drop-in: "taking final decisions when
> > consensus cannot be found otherwise."
>
> Actually, I was merely trying to replicate what the devrel stuff sais on
> this ;-) It isn't about a dispute on documentation aspects. If that were the
> case, I'd suggest a "consensus model" on the mailinglist and indeed project
> lead having a final say if consensus cannot be found.
>
> But when developers are more in dispute on non-documentation related
> aspects, the devrel guide/policy currently positions the project lead as a
> first mediator.
>
> Of course, we could just drop that part (since it already is in the policy)
> or rewrite it according to your suggestion (but then make it clear it is
> about project-related activities).
>
> Wkr,
> Sven Vermeulen
>

Well, adults are surprisingly good at acting like children. Mediator is a good
description for the task. Sometimes a tie-breaker vote is all that two
civilized and well-behaved adults need to resolve an "issue", but sometimes
there are real issues, perceived or otherwise, that need someone to really
mediate.

But, yeah, that responsibility is already defined by the Gentoo Policy.

--
Mr. Aaron W. Swenson
Pseudonym: TitanOfOld
Gentoo Developer

Gentoo doc RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.