Re: [gentoo-doc] Review of Documentation Policy

[Matt Turner]

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