Gentoo Archives: gentoo-doc

From: Matt Turner <mattst88@g.o>
To: gentoo-doc@l.g.o
Subject: Re: [gentoo-doc] Review of Documentation Policy
Date: Fri, 26 Aug 2011 02:46:46
In Reply to: Re: [gentoo-doc] Review of Documentation Policy by Joshua Saddler
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


Subject Author
Re: [gentoo-doc] Review of Documentation Policy "Francisco Blas Izquierdo Riera (klondike)" <klondike@g.o>