Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki

[AllenJB <gentoo-lists@allenjb.me.uk>]

On 04/04/10 08:31, Joshua Saddler wrote:
> <lots of stuff about what mediawiki supposedly can't do that is just completely untrue>

GuideXML may be better for the Handbook use case, with its ability to
produce single page and multipage documents, but frankly I think that
for the rest of the documentation, most of which only covers 1 or 2
pages, the ease of learning and editing mediawiki formats is far
superior. (I wouldn't be surprised if there's a way to reproduce this
single-page and multipage ability using inclusion on mediawiki)

I keep hearing this line about GuideXML not being hard to learn, but if
that's so true, why does Gentoo have so few developers contributing to
the documentation? Why does the current system basically rely on a
single developer tidying up and completing the documentation?

I've tried getting my head around GuideXML a few times and I hate
dealing with it. I much prefer to use the Gentoo Wiki, where I can just
throw stuff up really quickly using a syntax I use in many other places
and is well documented.

This line about learning wiki syntax is so old, but here's my reply yet
again: GuideXML is a non-tranferrable skill. Nowhere else in the entire
world uses it. Even if you haven't edited a wiki anywhere else, chances
are you probably will one day, and even if it's not mediawiki it'll
probably use syntax that's similar to it in many ways.

Syntax highlighting can easily be done with any of a number of plugins.
I'm sure ebuild syntax could be added without a massive amount of pain.

There are multiple ways to construct tables (wiki style, HTML and
probably some others - almost certainly more available via plugins),
some easier than others. And you can do styling either inline or in the
site-wide stylesheets.

Mediawiki has built-in intradoc linking to every heading, and in all the
use cases I've seen this level is fine. Intradoc linking to individual
letters^Wparas is just frankly way overboard (Does the Gentoo
documentation even use it anywhere?).

Wiki's may not be a magic bullet that'll solve all of Gentoo's problems,
but the current system doesn't seem to be working well, so something
needs to change, and I believe that a system that allows more people to
contribute more easily, using a syntax that's already widely used so is
either already known or an easily transferable skill is not a bad place
to start.

AllenJB