Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Michał Górny]

On Wed, 31 Oct 2012 17:26:38 +0100
Theo Chatzimichos <tampakrap@g.o> wrote:

> On Wed, Oct 31, 2012 at 1:39 PM, Michael Palimaka <kensington@g.o> 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.

-- 
Best regards,
Michał Górny