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
