From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from pigeon.gentoo.org ([208.92.234.80] helo=lists.gentoo.org) by finch.gentoo.org with esmtp (Exim 4.60) (envelope-from ) id 1NyRgB-0002vq-AQ for garchives@archives.gentoo.org; Sun, 04 Apr 2010 15:24:03 +0000 Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 1FDBCE0B5D; Sun, 4 Apr 2010 15:24:01 +0000 (UTC) Received: from mail-bw0-f223.google.com (mail-bw0-f223.google.com [209.85.218.223]) by pigeon.gentoo.org (Postfix) with ESMTP id 65AC0E0B4A for ; Sun, 4 Apr 2010 15:23:55 +0000 (UTC) Received: by bwz23 with SMTP id 23so517918bwz.26 for ; Sun, 04 Apr 2010 08:23:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:sender:received:in-reply-to :references:date:x-google-sender-auth:received:message-id:subject :from:to:content-type:content-transfer-encoding; bh=sSJ076d8s1TnGwt84g7S223s4Ip7aVy0EKuZm4s3yKs=; b=HKq+6G/wzvtnWfyhDEgYa5qXYSwqMsi0OQaF0J2micORva9yadoyPRElOjCOcbKQxq +gP2Xf6mb/2l12yZBJe6+xPT3555rdoA80yL3nkIbiSkdIt0OWlRCjbKK7Qqjvn0ExRs 5Sue0ObVOthR2hOCib2czQRGUJtzaarGsEJ4w= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:sender:in-reply-to:references:date :x-google-sender-auth:message-id:subject:from:to:content-type :content-transfer-encoding; b=ZIJOfsF5fcuKmce3RUdanr1QU+Ol7wh088Bj0yMkIB/1YQ3w8hG9Ebgiz43Lyf1zrR YW1Ob6Tzzc4O+sKgNG3f6MvImUUGCgAxArVL3q3UZsaICgqYTm4BXY2EoXA7+QutBd/a gc+pJlEkHJlbDJx/rUB44/PODZUPZ6E9fK6ac= Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org MIME-Version: 1.0 Sender: yngwin.gentoo@gmail.com Received: by 10.204.33.199 with HTTP; Sun, 4 Apr 2010 08:23:54 -0700 (PDT) In-Reply-To: <20100404003152.4b2012da@angelstorm> References: <20100403163010.1897d663@mail.a3li.li> <4BB7D11F.7060207@gentoo.org> <20100404003152.4b2012da@angelstorm> Date: Sun, 4 Apr 2010 17:23:54 +0200 X-Google-Sender-Auth: a0acaf3fcae55398 Received: by 10.204.22.9 with SMTP id l9mr3269678bkb.49.1270394634613; Sun, 04 Apr 2010 08:23:54 -0700 (PDT) Message-ID: Subject: Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki From: Ben de Groot To: gentoo-dev@lists.gentoo.org Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Archives-Salt: 69a1d0e2-5362-4b69-a97c-c9b86e2d54ea X-Archives-Hash: d06ac9adbdeed7f5668308b08b309264 On 4 April 2010 09:31, Joshua Saddler wrote: > On Sun, 4 Apr 2010 03:20:53 +0200 > Ben de Groot 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 >> =C2=A0 =C2=A0documentation, assembling upcoming meeting agendas, and so = on >> =C2=A0 =C2=A0[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 C= VS when going through document drafts? > 2) devspaces -- it's easy enough to dump stuff in here for others to refe= r to > > However, a wiki *does* make it easier for everyone to jump right in and e= dit stuff as ideas are passed around, rather than waiting for someone to ma= ke 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 >> =C2=A0 =C2=A0[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 do= c license somewhere. It's one of the reasons why we don't use existing unof= ficial wiki content in our docs. I and the GDP have written about that ad n= auseum 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 h= uge 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 d= o, 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, thou= gh neither of these have been qualified. As some others on this list have m= entioned, wiki syntax is downright ugly and simply not as consistent or rea= dable 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 wan= t 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 pret= ty 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 so= me 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, --=20 Ben de Groot Gentoo Linux Qt project lead developer