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 |