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

[Joshua Saddler]

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.

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

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

Show me a wiki that has built-in intradoc linking to every paragraph, chapter, subchapter, code sample, etc.

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

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>

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

From 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 syntax for either system, so pick your poison. 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.

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.