Gentoo Archives: gentoo-doc

From: Josh Saddler <nightmorph@g.o>
To: gentoo-doc@l.g.o
Subject: Re: [gentoo-doc] Handbooks / Autobuilds: What needs to be done?
Date: Thu, 30 Apr 2009 20:29:46
Message-Id: 49FA0A33.9010800@gentoo.org
In Reply to: Re: [gentoo-doc] Handbooks / Autobuilds: What needs to be done? by Nathan Zachary
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.

Attachments

File name MIME type
signature.asc application/pgp-signature

Replies