Re: [gentoo-doc] Handbooks / Autobuilds: What needs to be done?

[Josh Saddler]

Nathan Zachary wrote:
> Ben de Groot wrote:
>> To me this sounds like an issue that needs to be brought to the
>> attention of the council. Having good documentation has always been one
>> of the strengths of Gentoo. It would be sad to see that wither away
>> because of lack of manpower or lack of interest. Maybe we need to do
>> some targeted recruiting for the documentation team.

Eh, the council is a governing body for technical issues. They're all
about setting policy for things like Portage and ebuilds. I'm not sure
that they need to be bothered by what's going on in the GDP.

> I have contributed a document to the documentation team.

* Which, by the way, I'm examining today. :)

> Two people actively working on documents is not enough either, but it
> will hopefully offset some of the labour.  I don't think that the team
> would have any trouble finding volunteers to help out with editing, and
> that an announcement should be made on the forum.

Editing, or continual maintainance, is generally not a problem, assuming
that any bugs filed aren't for obscure subjects of which no one has any
knowledge. With the exception of big projects like updating all our docs
for OpenRC/Baselayout-2, the handbooks for autobuilds, or the Xorg guide
for xserver 1.5, even one person (me) can generally keep up with
day-to-day maintenance.

Where we really need help is in writing and maintaining *new*
documentation. Nate's Openbox draft is just the sort of thing that we need.

Now, on the forums and on our highly visible public mailing lists, I've
continually asked for help for years, wanting to get in some fresh new
talents to keep up with the English documentation. Unfortunately, since
I started helping write docs in 2005, we haven't seen a single new
dedicated English editor. Not someone who later becomes a developer, nor
a regular user from the Gentoo community.

Where we are more successful is in attracting new recruits for
translation teams. Our Internationalization subproject gets all the new
people. :)

I don't know that *advertising* is the problem . . . the problem is that
people just don't want to do the work. The most help we get is bug
reports (to varying degrees of helpfulness where they include
solutions), or occasional one-off new documents or substantial additions
to an existing guide.

I don't really blame folks for not wanting to do it, either -- there is
a lot of work to do. And it's not always something that can be satisfied
with a 30-second fix. Sure, in one weekend I may knock down our load of
bugs from 50 to 34, but in a couple of months it'll be back up to 50 or 60.

It takes a fair amount of dedicated time and effort to learn how
GuideXML and our coding style work. We have several tools and resources
available to help prospective recruits, but first someone has to show
willingness to learn. Not just willingness to learn, but the drive and
determination to improve our documentation by actually coming back and
contributing. :)

It's so extremely rare that it makes me think other distributions must
have the same manpower issues we do: it's just a universal "given" that
people don't want to write.