Re: [gentoo-dev] [Gentoo Phoenix] an official Gentoo wiki

[Ben de Groot]

On 4 April 2010 09:31, Joshua Saddler <nightmorph@g.o> wrote:
> On Sun, 4 Apr 2010 03:20:53 +0200
> Ben de Groot <yngwin@g.o> 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