On 4 April 2010 09:31, Joshua Saddler <nightmo...@gentoo.org> wrote: > On Sun, 4 Apr 2010 03:20:53 +0200 > Ben de Groot <yng...@gentoo.org> wrote: >> >> GuideXML documents are often experienced as an unnecessary >> >> barrier. >> > >> > I think you should clearly state again that this is not gonna replace >> > GuideXML, just migrate a few use cases where a wiki fits better. >> > This is what you aim for, right? > > No, he's definitely out to kill GuideXML. Just give him time.
Let me start by saying I immensely value the work you do, even tho we disagree on the merits of GuideXML. The GDP is an essential part of what makes Gentoo great, and I am willing to work with you to ensure that our documentation keeps the quality it is known for, and improve it where possible. Even if that means working with an (in my eyes) inferior technical solution. That said, I still hope I can convince you that working with a wiki has benefits over GuideXML and gorg. Some day. A man can hope... >> A wiki can fulfill several purposes for us: >> >> 1. Easy collaboration among devs, for brainstorming, developing new >> documentation, assembling upcoming meeting agendas, and so on >> [for which there currently is not really any obvious place] > > This is not *impossible* with our current setup; it can still be done in a > few different ways: > > 1) project spaces in /proj/$LANG/foobar/ -- how hard is it to commit to CVS > when going through document drafts? > 2) devspaces -- it's easy enough to dump stuff in here for others to refer to > > However, a wiki *does* make it easier for everyone to jump right in and edit > stuff as ideas are passed around, rather than waiting for someone to make > changes to something in a devspace. Nobody said it is impossible. It's just not very practical. And the fact that a growing number of official Gentoo projects are now using external wikis is an indication that we need to provide this ourselves. >> 3. A place to host and maintain our existing documentation >> [which is currently in GuideXML] > > Entirely unnecessary duplication of effort. To quote the forum mods, "don't > cross-post" . . . and especially don't do it if you'll be violating a doc > license somewhere. It's one of the reasons why we don't use existing > unofficial wiki content in our docs. I and the GDP have written about that ad > nauseum over the years; just search the list archives. Obviously we should not do anything that violates licenses, and I don't see anyone promoting that. As far as I can see there is agreement on using the CC-BY-SA license that is used in most of our documentation. This means we can't copy-paste content from the unofficial wiki. But in principle we could move existing official documentation into the wiki. Of course we would prefer to minimize duplication of effort. But having all (or at least most) of our documentation in one place has obvious benefits. So I hope I can convince the GDP to join us. >> I am not pushing for our existing documentation to be migrated into a >> wiki at this point. But I think that once the place is there, and it >> functions well, it would be the obvious next step to do so. As I said >> before, the barrier to contributing and maintaining documentation is >> much higher in the case of GuideXML, so it doesn't really make sense >> to keep that around when we have a better solution. >> >> I know there are people who do not agree with me on this last point > > . . . to say the least. > > Show me a wiki that has the flexibility of our handbook, which can be a huge > printer-friendly all-in-one doc, or an as-you-need-it doc with one page per > chapter. As far as I know, we only use this functionality for our handbook. But MediaWiki can do that with what they call transclusion. > Show me a wiki that [does a number of things] MediaWiki (like any major wiki) can do all those things. You are basically showing your ignorance of wikis. Your arguments against wikis seem to be based on your false impressions of them, not on actual facts. As has been pointed out, your table example was unfair, as they don't do the same thing. I would frown on such inline styling (that's what stylesheets are for), and there are a number of ways you can markup tables in wikis. One is to allow HTML tags, so it would be very much like GuideXML. Another one, which I prefer personally, is to use reStructuredText, which is even clearer than HTML markup. > By moving to a wiki, you'll lose a huge percentage of what GuideXML can do, I don't see that at all. Is there any essential feature of GuideXML that is missing in MediaWiki? (Let's take that wiki implementation as the most likely one we will adopt.) I haven't seen anything yet that is impossible or very difficult to do. Do you really think that GuideXML is so special and advanced that nobody else had the same needs and that major wiki engines do not provide in those needs? > in exchange for "quicker" and "easier" editing and creation of docs, though > neither of these have been qualified. As some others on this list have > mentioned, wiki syntax is downright ugly and simply not as consistent or > readable as plain ol' XML or HTML. Wikis can use various markup systems. Whether the default wiki syntax is ugly, is debatable. I don't think it's that bad, but it certainly isn't perfect. As I've mentioned before, personally I prefer to use reStructuredText, which is quite elegant, very readable and easy to pick up. You could also use straight HTML markup, if you wanted to. But most people seem to prefer standard wiki syntax. And if you really wanted to, you could easily write an extension to parse GuideXML, so it could be used as wiki markup. So again, the markup is not really an argument against using a wiki instead of our current GuideXML+gorg setup. > From what I've seen, the biggest objection to GuideXML is folks don't want to > take the time to learn a few tags. No, that's not it. The two main objections, from what I can see are: 1. It is confusing, because it is an XML dialect that is similar to HTML, shares a number of tags, but then substitutes some for others, and has (for the casual user) seemingly arbitrary restrictions. 2. It is a non-transferable skill. You can't use it anywhere else. And unless you are a regular GuideXML writer, you will have to look up its particular usage almost every time you do use it. > I've yet to see a wiki that even has as much sense as HTML, which is pretty > low on the totem pole of consistency. That's a non-argument as I showed above. > I ain't out to stop ya'll from using a wiki. I do agree that they have some > advantages. However, I will point out how limited wikis are. They're not a > magic bullet that will solve all our problems. Nobody is saying they are a magic bullet. But they are not as limited as you believe they are. And a lot of people agree they are a better solution than what we currently have. Cheers, -- Ben de Groot Gentoo Linux Qt project lead developer
