On Thu, Nov 1, 2012 at 5:34 PM, Michał Górny <mgo...@gentoo.org> wrote: > On Wed, 31 Oct 2012 17:26:38 +0100 > Theo Chatzimichos <tampak...@gentoo.org> wrote: > >> On Wed, Oct 31, 2012 at 1:39 PM, Michael Palimaka <kensing...@gentoo.org> >> wrote: >> > Hi all, >> > >> > In bug #304435[1], hwoarang suggested merging the devrel handbook[2] into >> > the devmanual[3]. >> > >> > As the project has grown, so has the amount - and dispersion - of >> > development information. I believe consolidation of this information into a >> > single point will make everyone's (especially new developers) lives easier. >> > >> > What do you think? >> > >> > Best regards, >> > Michael >> > >> > [1]: https://bugs.gentoo.org/show_bug.cgi?id=304435 >> > [2]: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml >> > [3]: http://devmanual.gentoo.org/ >> >> +1 and btw move the devmanual in the wiki :D > > I'm not sure if wiki fits nicely here. I believe that wiki is very > useful at taking notes, writing quick guides and sharing information > and tips in general. The main advantage is the free workflow -- you > have an idea to share but can't do it all by yourself. You start it, > others can easily improve it. > > Sadly, our wiki is MediaWiki. Not getting deep into it, the syntax is > worse than awful. It could be considered acceptable if you write > encyclopedia articles, stuff with heavy inside linking and not much > code inside. However, for technical articles it is horrible, horrible > and once more horrible. > > Shortly saying, devmanual in wiki would mostly consist of HTML tagsoup > intermixed with wiki text. For the very simple reason that MediaWiki > lags markup for as basic things as inline code and requires you to use > HTML instead. Not something I'd use for anything as fundamental > as devmanual.
Rosetta Code (my site) runs MediaWiki. I can attest to the terrible thing that is MW syntax. That said, we did ultimately come up with workarounds for 98% of the problems. (Most of the remaining 2% are spammers...and that comes down to a question of strongly you lock the thing down.) I've submitted patches to Gentoo docs before. Honestly, I found it a pain; I'm not accustomed to that particular process. Admittedly, this is one of those cases where I simply lack an attainable skill. If nothing else, I'd love to see the docs all reside in Git; I could fork to my Github account and generate pull requests from there. A proper maintainer could review the pull request and decide whether or not to merge it. That would be a much more comfortable workflow, IMO. (Heck, I wouldn't mind migrating RC to a similar workflow; I'd just have to migrate gigabytes worth of wikitext history to a format with new semantics...) -- :wq
