Gentoo Archives: gentoo-dev

From: Ben de Groot <yngwin@g.o>
To: gentoo-dev@l.g.o
Subject: Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki
Date: Sun, 04 Apr 2010 15:24:03
In Reply to: Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki by Joshua Saddler
1 On 4 April 2010 09:31, Joshua Saddler <nightmorph@g.o> wrote:
2 > On Sun, 4 Apr 2010 03:20:53 +0200
3 > Ben de Groot <yngwin@g.o> wrote:
4 >> >> GuideXML documents are often experienced as an unnecessary
5 >> >> barrier.
6 >> >
7 >> > I think you should clearly state again that this is not gonna replace
8 >> > GuideXML, just migrate a few use cases where a wiki fits better.
9 >> > This is what you aim for, right?
10 >
11 > No, he's definitely out to kill GuideXML. Just give him time.
13 Let me start by saying I immensely value the work you do, even tho
14 we disagree on the merits of GuideXML. The GDP is an essential part
15 of what makes Gentoo great, and I am willing to work with you to
16 ensure that our documentation keeps the quality it is known for, and
17 improve it where possible. Even if that means working with an (in my
18 eyes) inferior technical solution.
20 That said, I still hope I can convince you that working with a wiki
21 has benefits over GuideXML and gorg. Some day. A man can hope...
23 >> A wiki can fulfill several purposes for us:
24 >>
25 >> 1. Easy collaboration among devs, for brainstorming, developing new
26 >>    documentation, assembling upcoming meeting agendas, and so on
27 >>    [for which there currently is not really any obvious place]
28 >
29 > This is not *impossible* with our current setup; it can still be done in a few different ways:
30 >
31 > 1) project spaces in /proj/$LANG/foobar/ -- how hard is it to commit to CVS when going through document drafts?
32 > 2) devspaces -- it's easy enough to dump stuff in here for others to refer to
33 >
34 > 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.
36 Nobody said it is impossible. It's just not very practical. And the
37 fact that a growing number of official Gentoo projects are now using
38 external wikis is an indication that we need to provide this
39 ourselves.
41 >> 3. A place to host and maintain our existing documentation
42 >>    [which is currently in GuideXML]
43 >
44 > 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.
46 Obviously we should not do anything that violates licenses, and I
47 don't see anyone promoting that. As far as I can see there is
48 agreement on using the CC-BY-SA license that is used in most of our
49 documentation. This means we can't copy-paste content from the
50 unofficial wiki. But in principle we could move existing official
51 documentation into the wiki.
53 Of course we would prefer to minimize duplication of effort. But
54 having all (or at least most) of our documentation in one place has
55 obvious benefits. So I hope I can convince the GDP to join us.
57 >> I am not pushing for our existing documentation to be migrated into a
58 >> wiki at this point. But I think that once the place is there, and it
59 >> functions well, it would be the obvious next step to do so. As I said
60 >> before, the barrier to contributing and maintaining documentation is
61 >> much higher in the case of GuideXML, so it doesn't really make sense
62 >> to keep that around when we have a better solution.
63 >>
64 >> I know there are people who do not agree with me on this last point
65 >
66 > . . . to say the least.
67 >
68 > 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.
70 As far as I know, we only use this functionality for our handbook.
71 But MediaWiki can do that with what they call transclusion.
73 > Show me a wiki that [does a number of things]
75 MediaWiki (like any major wiki) can do all those things. You are
76 basically showing your ignorance of wikis. Your arguments against
77 wikis seem to be based on your false impressions of them, not on
78 actual facts.
80 As has been pointed out, your table example was unfair, as they don't
81 do the same thing. I would frown on such inline styling (that's what
82 stylesheets are for), and there are a number of ways you can markup
83 tables in wikis. One is to allow HTML tags, so it would be very much
84 like GuideXML. Another one, which I prefer personally, is to use
85 reStructuredText, which is even clearer than HTML markup.
87 > By moving to a wiki, you'll lose a huge percentage of what GuideXML can do,
89 I don't see that at all. Is there any essential feature of GuideXML
90 that is missing in MediaWiki? (Let's take that wiki implementation as
91 the most likely one we will adopt.) I haven't seen anything yet that
92 is impossible or very difficult to do. Do you really think that
93 GuideXML is so special and advanced that nobody else had the same
94 needs and that major wiki engines do not provide in those needs?
96 > 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.
98 Wikis can use various markup systems. Whether the default wiki syntax
99 is ugly, is debatable. I don't think it's that bad, but it certainly
100 isn't perfect. As I've mentioned before, personally I prefer to use
101 reStructuredText, which is quite elegant, very readable and easy to
102 pick up. You could also use straight HTML markup, if you wanted to.
103 But most people seem to prefer standard wiki syntax.
105 And if you really wanted to, you could easily write an extension to
106 parse GuideXML, so it could be used as wiki markup. So again, the
107 markup is not really an argument against using a wiki instead of our
108 current GuideXML+gorg setup.
110 > From what I've seen, the biggest objection to GuideXML is folks don't want to take the time to learn a few tags.
112 No, that's not it. The two main objections, from what I can see are:
114 1. It is confusing, because it is an XML dialect that is similar to
115 HTML, shares a number of tags, but then substitutes some for
116 others, and has (for the casual user) seemingly arbitrary
117 restrictions.
118 2. It is a non-transferable skill. You can't use it anywhere else.
119 And unless you are a regular GuideXML writer, you will have to
120 look up its particular usage almost every time you do use it.
122 > 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.
124 That's a non-argument as I showed above.
126 > 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.
128 Nobody is saying they are a magic bullet. But they are not as limited
129 as you believe they are. And a lot of people agree they are a better
130 solution than what we currently have.
132 Cheers,
133 --
134 Ben de Groot
135 Gentoo Linux Qt project lead developer


Subject Author
Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki Joshua Saddler <nightmorph@g.o>