Linux Archive

Linux Archive (http://www.linux-archive.org/)
-   Gentoo Documentation (http://www.linux-archive.org/gentoo-documentation/)
-   -   Review of Documentation Policy (http://www.linux-archive.org/gentoo-documentation/564629-review-documentation-policy.html)

Sven Vermeulen 08-15-2011 09:23 PM

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

Matt Turner 08-15-2011 09:46 PM

Review of Documentation Policy
 
On Mon, Aug 15, 2011 at 5:23 PM, Sven Vermeulen <swift@gentoo.org> 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

Matt Turner 08-15-2011 09:46 PM

Review of Documentation Policy
 
On Mon, Aug 15, 2011 at 5:23 PM, Sven Vermeulen <swift@gentoo.org> 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

Sven Vermeulen 08-19-2011 05:22 PM

Review of Documentation Policy
 
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

Matt Turner 08-23-2011 12:16 AM

Review of Documentation Policy
 
On Fri, Aug 19, 2011 at 1:22 PM, Sven Vermeulen <swift@gentoo.org> 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

Sven Vermeulen 08-23-2011 08:52 AM

Review of Documentation Policy
 
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

Matt Turner 08-23-2011 01:43 PM

Review of Documentation Policy
 
On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <swift@gentoo.org> 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

Joshua Saddler 08-25-2011 05:41 AM

Review of Documentation Policy
 
On Tue, 23 Aug 2011 09:43:51 -0400
Matt Turner <mattst88@gentoo.org> wrote:

> On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <swift@gentoo.org>
> 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/.

Matt Turner 08-26-2011 02:45 AM

Review of Documentation Policy
 
On Thu, Aug 25, 2011 at 1:41 AM, Joshua Saddler <nightmorph@gentoo.org> wrote:
> On Tue, 23 Aug 2011 09:43:51 -0400
> Matt Turner <mattst88@gentoo.org> wrote:
>
>> On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <swift@gentoo.org>
>> 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

"Francisco Blas Izquierdo Riera (klondike)" 08-31-2011 09:59 PM

Review of Documentation Policy
 
El 26/08/11 04:45, Matt Turner escribió:
> On Thu, Aug 25, 2011 at 1:41 AM, Joshua Saddler <nightmorph@gentoo.org> wrote:
>> On Tue, 23 Aug 2011 09:43:51 -0400
>> Matt Turner <mattst88@gentoo.org> wrote:
>>
>>> On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <swift@gentoo.org>
>>> 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.


All times are GMT. The time now is 10:18 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.