On Sat, 03 Oct 2009 15:54:31 +0100 AllenJB <gentoo-li...@allenjb.me.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
signature.asc
Description: PGP signature
