Re: Review of Documentation Policy

On Tue, 23 Aug 2011 09:43:51 -0400
Matt Turner <[email protected]> wrote:

> On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <[email protected]>
> 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/.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.17 (GNU/Linux)

iEYEARECAAYFAk5V4HAACgkQxPWMzpKk6kMZjACgiCWBeUBw2ZZGkKeWUi0O8Had
0r4AoL2lVX05W+iCojmkYSItaulsu1oz
=WXaO
-----END PGP SIGNATURE-----