Re: [gentoo-doc] Review of Documentation Policy

[Francisco Blas Izquierdo Riera (klondike)]

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