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 1NyKJh-0000EX-I7 for garchives@archives.gentoo.org; Sun, 04 Apr 2010 07:32:30 +0000 Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 70E7DE0B76; Sun, 4 Apr 2010 07:32:12 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by pigeon.gentoo.org (Postfix) with ESMTP id AA98FE0B64 for ; Sun, 4 Apr 2010 07:31:58 +0000 (UTC) Received: from angelstorm (cpe-76-93-187-113.san.res.rr.com [76.93.187.113]) (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTP id 2D7651B4033 for ; Sun, 4 Apr 2010 07:31:58 +0000 (UTC) Date: Sun, 4 Apr 2010 00:31:52 -0700 From: Joshua Saddler To: gentoo-dev@lists.gentoo.org Subject: Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki Message-ID: <20100404003152.4b2012da@angelstorm> In-Reply-To: References: <20100403163010.1897d663@mail.a3li.li> <4BB7D11F.7060207@gentoo.org> X-Mailer: Claws Mail 3.7.5 (GTK+ 2.18.7; x86_64-pc-linux-gnu) 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 Content-Type: multipart/signed; micalg=PGP-SHA1; boundary="Sig_/IIAkJmkftJyXKqV0FFD/R/9"; protocol="application/pgp-signature" X-Archives-Salt: 978296e9-6956-4097-b866-cf7d809bc2ba X-Archives-Hash: bf90a67fd64c2a3c97339832f51fba20 --Sig_/IIAkJmkftJyXKqV0FFD/R/9 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable 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. > A wiki can fulfill several purposes for us: >=20 > 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 edi= t stuff as ideas are passed around, rather than waiting for someone to make= changes to something in a devspace. > 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 unoffi= cial wiki content in our docs. I and the GDP have written about that ad nau= seum over the years; just search the list archives. =20 > 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. >=20 > 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 hug= e printer-friendly all-in-one doc, or an as-you-need-it doc with one page p= er chapter. Show me a wiki that has built-in intradoc linking to every paragraph, chapt= er, subchapter, code sample, etc. Show me a wiki that produces such beautiful code samples (with titles). Sho= w me a wiki that can produce the following formatting for ebuilds: http://www.gentoo.org/doc/en/xml-guide.xml#doc_chap2_sect7 . . . or a wiki that makes it super-easy to add all sorts of additional in-= line formatting to regular paragraphs, for example all the blue highlightin= g for code used throughout http://www.gentoo.org/doc/en/xml-guide.xml, or t= he monospace font used for filesystem paths. Show me a wiki that makes it easy to create tables, for example, compare Ra= deonProgram from the x.org wiki: http://www.x.org/wiki/RadeonProgram?action=3Dedit ||<-2 style=3D"text-align: center; background-color: #666666"> '''Native'''= || '''R100''' ||<= style=3D"text-align: center; background-color: #666666"> '''R200''' || '''R300''' || '''R400''' || '''RS690''' || '''R500''' || '''R600''' || '''R700''' || . . . that's one line of cells. One. Ugly. Compare it to: http://www.gentoo.org/doc/en/xml-guide.xml#doc_chap5_pre1 This is an example for indentationmore stuff
Foo Bar
Which is easier to read and instantly comprehend? By moving to a wiki, you'll lose a huge percentage of what GuideXML can do,= in exchange for "quicker" and "easier" editing and creation of docs, thoug= h neither of these have been qualified. As some others on this list have me= ntioned, wiki syntax is downright ugly and simply not as consistent or read= able as plain ol' XML or HTML. =46rom what I've seen, the biggest objection to GuideXML is folks don't want = to take the time to learn a few tags. Well, you'll have to learn tags and s= yntax for either system, so pick your poison. I've yet to see a wiki that e= ven has as much sense as HTML, which is pretty low on the totem pole of con= sistency. 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. --Sig_/IIAkJmkftJyXKqV0FFD/R/9 Content-Type: application/pgp-signature; name=signature.asc Content-Disposition: attachment; filename=signature.asc -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.14 (GNU/Linux) iEYEARECAAYFAku4QGoACgkQxPWMzpKk6kPA/ACeMFwPNVb8siWrhAbM1PJKWt3h lKAAoI5HZNI+mRaNWB6X5AbDK52fexnV =qmFJ -----END PGP SIGNATURE----- --Sig_/IIAkJmkftJyXKqV0FFD/R/9--