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

[Ryan Hill]

On Sat, 03 Oct 2009 15:54:31 +0100
AllenJB <gentoo-lists@××××××××××.uk> wrote:

> I personally would happily donate my time to working on the docs, if
> only it didn't involve a markup language nobody else uses. I suggested a
> closed wiki for official documentation, but was again shot down saying
> that the existing team (who seem to be doing nothing) would need to
> reskill and that the server admins dislike wikis.

While I don't think there's anything wrong with our official docs being where
they are now, I'd kill for a dev-wiki to document the thousands of things we
all need to know that aren't written down anywhere.

And I know the response to this is going to be "if there's something that
should be documented, file a bug and get it into the dev manual/handbook".
While the dev manual is a good general overview of Gentoo development, there
is still a lot of stuff that isn't appropriate to document there.  Having a
spot for package-specific maintenance docs was brought up a couple years ago
and shot down.  Any documentation someone writes that doesn't fit into any
particular project ends up in someone's dev-space, where it's hard to find
unless you know it's there, dependent on one person to keep current, and lost
if that person retires.  I've wanted to do gcc-porting guides for the last
couple releases, but I have nowhere to put them and am too slow/lazy to
figure out GuideXML and put them in my dev-space, where no one would see
them.  We also have any number of "best practices" in Gentoo that generally
can only be discovered by breaking them and getting people annoyed with you;
things such as when it's okay to filter flags, how to use RESTRICT to handle
upstream changing a distfile without a name change, or when it's better to
not use a USE flag and just force an option.  These things might be
appropriate for the dev manual but would benefit much more from the kind of
collaboration you get with a wiki environment.  Development is a dynamic
thing and requires dynamic documentation.


-- 
fonts,                             Character is what you are in the dark.
gcc-porting,
wxwidgets @ gentoo     EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662