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

[Ed W]

Hi

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

Yes, but the wiki layout is badly written, you should be comparing it to:


|| '''Native''' || '''R100''' || '''R200''' || '''R300''' || '''R400''' || '''RS690''' || '''R500''' || '''R600''' || '''R700''' ||


I think this reads ok?  In fact with a bit of thought from some premade 
styles even the ''' bit should go?


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

I think this summarises the basic tradeoff - you trade editing speed for 
"simplicity" of syntax and readability.  Clearly as your example shows 
it's possible to write complicated looking stuff in any syntax though, 
but in general wiki's win where the content is most important and 
styling is done separately using CSS (a bit like guideXML really)

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

I think this is a point of contention.  Certainly it was a design goal 
for the wiki syntax to be simple and easily readable, but one man's 
"simple" is another mans XML...


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

Actually I think GuideXML is excellent - if there is a wiki style engine 
which allows you to post in GuideXML then we should do it?

I think it's not an objection to the GuideXML which is the problem, but 
creating a system which can be edited quickly and easily in a granular 
fashion.  Eg imagine all the guideXML docs being in a git repo with open 
access to pull/push changes - you could build a web engine around that 
which rebuilds the web pages interactively as people push edits and this 
would be cool!  In the meantime wiki's are just trying to solve the same 
goal of easy edits with small granularity of edits

However, I love the idea of a "wiki" based around git using GuideXML! 
(probably it kind of works like this right now - I think it's the access 
control which is the secret sauce...)

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

Definitely.

Good luck

Ed W