[Bf-docboard] mediawiki vs docbook

[Bart Veldhuizen]

Hi all,

just to give my 2 cents of input:

As far as I'm concerned there's only one issue: lowering the barrier  
for people who are interested in contributing to the documentation.  
Having to set up a docbook environment and having to learn how to  
work with CVS may seem appealing to geeks (such as me ;-) but it will  
scare away 90% of the interested audience.

The only think I would be looking for is an easy to learn, online  
cross-OS system that does not require someone to install specific  
software that would allow people to contribute after spending only 10  
minutes learning how to work with the system. I consider the rest  
(how to prepare offline archives, how to prepare for print etc) to be  
of lower priority.

My advice would be to first write down the functional demands that we  
should have on such a system, and only then worry about technology.

Bart


Op 19-aug-2005, om 17:06 heeft David Millet het volgende geschreven:

> Hi all,
>
> Stefano and I have been chatting a bit today; he feels strongly  
> that there's something better than docbook out there and so he's  
> been asking me a lot of questions about media wiki.  He's asked me  
> to share the strong points of media wiki with the rest of the list.
>
> 1) Mediawiki is easier to write with.
>     - the formatting is easy to learn and very quick to type.  For  
> example:
>         - for images: [[Image:myImage.png]]
>         - for italics: ''my italicized text''
>         - for bold: '''my bold'''
>         - for indenting an entire paragraph, just use ":"  
> -    :this is my paragraph and I will be indented
>         - for indenting the paragraph twice-    ::this paragraph is  
> indented twice
>
> 2) Mediawiki does not require heavy uploads every time you make  
> changes (which if I understand correctly was caused by CVS).  It  
> comes with it's own versioning system that makes it simple to  
> compare differences between any two versions of a page, and it's  
> simple to revert back to previous versions, all within the same  
> wiki interface.
>
> 3) Mediawiki will take the HTML from docbook pages and accept it  
> just fine, we can just copy and paste from the old into the new.   
> the mediawiki engine will take straight HTML as well as the other  
> formatting.... you don't have to use wiki formatting such as ''' or  
> [[ ]] when you create pages, if you don't want, although it is  
> quicker to do so.
>
> 4) Mediawiki will simultaneously offer us the opportunity to  
> control who's editing pages of the book, but allow everyone in the  
> world to participate in discussions about the state of each page of  
> the book.  if you want to see what i mean about the discussions,  
> check out this discussion for the Noob to Pro wikibook front page:  
> http://en.wikibooks.org/wiki/Talk:Blender_3D:_Noob_to_Pro  .  The  
> community will be allowed to see the book in open development and  
> provide feedback, which some of you may like and others may not,  
> but hey, a little bit of community feedback never killed anyone,  
> right? ;)
>
> 5) Mediawiki will also allow us to create community editable  
> sections where they can further discuss the documentation and write  
> sample documentations so that they can be considered to be  
> authors.  Nothing creates a instant community like a wiki.
>
> 6) The whole mediawiki interface is easily customizable through  
> HTML templates.  New functionality is simple to program in if you  
> know PHP and MySQL (which I do, and I know quite a few other  
> Blender guys that do as well).
>
> Well, this is a bit longer than I intended it to be, and I hope  
> you'll forgive me for that.  If you have any questions or feedback,  
> you know what to do ;)  Stefano needs good information for both  
> sides in order to make a good decision on the matter, so I hope you  
> all will sound off with some sage reasoning on the pros and cons of  
> both.
>
> David Millet
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at projects.blender.org
> http://projects.blender.org/mailman/listinfo/bf-docboard
>