Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?

[Joshua Saddler]

On Sun, 04 Oct 2009 00:58:56 +0100
AllenJB <gentoo-lists@××××××××××.uk> wrote:
> I have no intention of "shitting all over" anybodys work. My apologies
> if that was the interpretation. I'm simply escalating an issue I have
> raised before to somewhere I think it'll get more attention.

I realize (now) it wasn't your intention. But that was how I took it. Just sayin'.

> Maybe you're not totally dead, but my criteria for activity has been the
> multiple bugs I've been sitting on and the number of times I'm having to
> tell new users "the handbook is wrong, ignore it and follow my
> instructions in this case" or "oh dear! You seem to have installed a
> version of Portage so ancient that 99% of our package tree can't be
> installed" (or words to that effect) - mostly to do with the lack of
> up-to-date handbooks, which as per my original post is now becoming a
> dire situation, in my opinion.

It is pretty bad -- it's news to me that EAPI2 is causing installation issues. That's on top of the interesting outdated packages and blockers seen when updating from something as old as 2008.

Problem is that there is no real "quick fix" for the handbooks, and there never was, even when the autobuilds were first introduced. It's not just a matter of changing version numbers. It's also the supporting text. It's also the variable infrastructure in our other handbooks that build the displayed text using a number of conditionals. Every file we have needs to be overhauled to match what should be a simple version change, because the autobuilds are very different.

Give me two or three straight days that I devote 12 hours of work to the docs per day, and three GDP members who can work some or all of that time, and I can get the handbooks done in a weekend. It's doable, it just needs a large block of time, and more people besides me doing all the work.

I've been doing solo handbook overhauls for the last several releases. It's not fun anymore. This is even more wide-reaching than that, since it involves core handbook design decisions that (I think) *require* getting my fellow team members and lead to review and consider.

> If the rest of the team is dead, why not escalate the issue to, say the
> -dev list. At least from what you've said in your most recent post you
> seem to think _something_ does need to be done about the current situation.

This is an idea, but I don't know that it would accomplish much. I've chimed in on major package changes on the -dev list with a request for developers to talk with the GDP regarding related doc updates, but most of those kinds of requests go unanswered, or are answered very slowly.

Usually I jump on IRC as it's more likely that I'll enlist help from my fellow developers there, in real time: two very recent examples are the Xfce and X11 teams helping me out with my questions regarding the guides for 'em, and some stuff on bugzilla.

Something does need to be done about the number of active docs developers, and the number of non-GDP members contributing patches that I just need to commit with minimal review, thus acting as a commit proxy. But I can't *force* people to help out with the documentation -- that includes users and developers. Nor can I force our developers to have free time right when *I* need some answers WRT a doc.