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

[Alex Legler]

On Sun, 4 Apr 2010 00:31:52 -0700, Joshua Saddler
<nightmorph@g.o> wrote:

>
> No, he's definitely out to kill GuideXML. Just give him time.
>

At least for official documentation, that should not happen.

(That excludes non-doc parts of the website though imo. GuideXML is a
XML "DSL" designed for documentation, sadly it sucks for doing
websites.)

> > A wiki can fulfill several purposes for us:
> >
> [...]
>
> 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.
>

That's why we should want a wiki for general collaboration.

> > 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.

ack. It should /not/ be a goal of the Wiki to maintain official docs.

> [...]
> Show me a wiki that produces such beautiful code samples (with
> titles).
> [...]
> . . . 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 highlighting for code used throughout
> http://www.gentoo.org/doc/en/xml-guide.xml, or the monospace font
> used for filesystem paths.
>

Let's be honest: Such things can be arranged. Most Wikis have a {{foo}}
-> <tt>foo</tt> syntax already built in.

> Show me a wiki that makes it easy to create tables, for example,
> compare RadeonProgram from the x.org wiki:
>
> http://www.x.org/wiki/RadeonProgram?action=edit
>
> ||<-2 style="text-align: center; background-color: #666666">
> '''Native''' ||<style="text-align: center; background-color:
> #666666"> '''R100''' ||<style="text-align: center; background-color:
> #666666"> '''R200''' ||<style="text-align: center; background-color:
> #666666"> '''R300''' ||<style="text-align: center; background-color:
> #666666"> '''R400''' ||<style="text-align: center; background-color:
> #666666"> '''RS690''' ||<style="text-align: center; background-color:
> #666666"> '''R500''' ||<style="text-align: center; background-color:
> #666666"> '''R600''' ||<style="text-align: center; background-color:
> #666666"> '''R700''' ||
>
>
> . . . that's one line of cells. One. Ugly. Compare it to:
>
> http://www.gentoo.org/doc/en/xml-guide.xml#doc_chap5_pre1
>
> <table>
> <tr>
>   <th>Foo</th>
>   <th>Bar</th>
> </tr>
> <tr>
>   <ti>This is an example for indentation</ti>
>   <ti>more stuff</ti>
> </tr>
> </table>
>

Meep. That's an unfair one.
The guidexml snippet does not contain any styling. (Oh wait, I forgot,
it doesn't even support styling. [another reason why it sucks for
websites])

> [...]
>
> 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.

Again: Official docs should not be considered as Wiki material indeed.
Of course if someone feels like experimenting with such things in the
Wiki, feel free to. If the experiment should be really successful, the
GDP might reconsider.
But it's still the GDP's sandbox and as long as they're playing in it,
don't take away their toys.

Let's work *together* towards a better Gentoo, so let's consider the
official docs off-limits for the Wiki effort (at least for now) as
there are valid reasons against such a thing.

Alex

-- 
Alex Legler | Gentoo Security / Ruby
a3li@g.o | a3li@××××××××××.de