Gentoo Archives: gentoo-dev

From: AllenJB <gentoo-lists@××××××××××.uk>
To: gentoo-dev@l.g.o
Subject: Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki
Date: Sun, 04 Apr 2010 10:35:36
Message-Id: 4BB86B6A.4060500@allenjb.me.uk
In Reply to: Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki by Joshua Saddler
1 On 04/04/10 08:31, Joshua Saddler wrote:
2 > <lots of stuff about what mediawiki supposedly can't do that is just completely untrue>
3
4 GuideXML may be better for the Handbook use case, with its ability to
5 produce single page and multipage documents, but frankly I think that
6 for the rest of the documentation, most of which only covers 1 or 2
7 pages, the ease of learning and editing mediawiki formats is far
8 superior. (I wouldn't be surprised if there's a way to reproduce this
9 single-page and multipage ability using inclusion on mediawiki)
10
11 I keep hearing this line about GuideXML not being hard to learn, but if
12 that's so true, why does Gentoo have so few developers contributing to
13 the documentation? Why does the current system basically rely on a
14 single developer tidying up and completing the documentation?
15
16 I've tried getting my head around GuideXML a few times and I hate
17 dealing with it. I much prefer to use the Gentoo Wiki, where I can just
18 throw stuff up really quickly using a syntax I use in many other places
19 and is well documented.
20
21 This line about learning wiki syntax is so old, but here's my reply yet
22 again: GuideXML is a non-tranferrable skill. Nowhere else in the entire
23 world uses it. Even if you haven't edited a wiki anywhere else, chances
24 are you probably will one day, and even if it's not mediawiki it'll
25 probably use syntax that's similar to it in many ways.
26
27 Syntax highlighting can easily be done with any of a number of plugins.
28 I'm sure ebuild syntax could be added without a massive amount of pain.
29
30 There are multiple ways to construct tables (wiki style, HTML and
31 probably some others - almost certainly more available via plugins),
32 some easier than others. And you can do styling either inline or in the
33 site-wide stylesheets.
34
35 Mediawiki has built-in intradoc linking to every heading, and in all the
36 use cases I've seen this level is fine. Intradoc linking to individual
37 letters^Wparas is just frankly way overboard (Does the Gentoo
38 documentation even use it anywhere?).
39
40 Wiki's may not be a magic bullet that'll solve all of Gentoo's problems,
41 but the current system doesn't seem to be working well, so something
42 needs to change, and I believe that a system that allows more people to
43 contribute more easily, using a syntax that's already widely used so is
44 either already known or an easily transferable skill is not a bad place
45 to start.
46
47 AllenJB