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

[Nathan Zachary]

Josh Saddler wrote:
> 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.
>
>
I'm also thinking about doing some documentation on LXDE, and PekWM as 
well.  If there is anything in particular that needs documentation, I'd 
be happy to look into the issues, even if I don't have previous 
knowledge or experience.  I have several test machines on which I can 
try new configurations. :)

--Zach