User talk:Spiderworm/blog

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

... Part from: http://projects.blender.org/pipermail/bf-docboard/2005-August/002305.html

Hi,

I've got too much mails already, so have disabled the docboard mailing list to send mails to me. :) The web archive is available though, so I've scanned the past discussion on DocBook vs. Wiki. Here's a couple  of notes;

- Printed books Yes, the Blender Foundation completely depends on sales of manuals, so we will need to start working on a 2.4 manual update as well. However, that is not something the docboard should worry about too much, apart from keeping the docs on Blender well structured and accessible. The choice for DocBook didn't really help us for making a book about Blender. The exporting formats as available completely failed to work in the Adobe Indesign software (which the DTP designers used). I also hear Stefano regularly complaining about bugs in DocBook, like for exporting to pdfs. So, if we want to make another book, we already know that the book Editor and the designers will have to do a lot of manual labour to get the docs content into print. The 2.3 book took 4 months to produce... I also consider this work 'professional', the people who make this happen get paid for it. Conclusion; it's not so much the format that matters, but how well structured the content itself is. Is it well formatted (chapter structure)? Are the screenshots of a standard quality?

- DocBook I have the impression that the biggest fans of DocBook are not the people who contribute to our docboard project... at least, this was how the choice was initially done. I've tried myself to work with it, and I can only say the design of the DocBook XML tags system is a nightmare. It hasn't been designed to work with easily, unless you use a WYSIWYG editor, which I didn't find back then (when we did 2.3 manual). Googling around on DocBook, I find a lot of debates on the topic. The most passionate supporters of DocBook are (typical!) Linux authors who've written a book themselves. For a community oriented project it seems to be less succesful.

- DocBoard mission statement The docboard could focus on the following two issues: 1) Make available the standard end-user documentation on Blender, in an open online (browsable) and offline (downloadable) format. 2) Organize an accessible documentation project, to enable motivated authors to contribute as efficient as possible. As sub-target you could add; 3) Format the documentation in such a way that third parties (or Blender Foundation) can use it for creating printed books.

- Other formats...? The discussion to switch to (for example) MediaWiki should be about: 1) What format gives best online and offline access to Blender docs? 2) What format pleases motivated (active contributing) authors best?

A decision on this should really be limited to the people who actually did write a lot of Blender documentation in the past. We need people who love to work on docs, and are movitvated to continue working on it in the future too. :)

-Ton-

Well, I will still use MediaWiki, if they like it or not:) Hey, did you see cool new WikiTeX features? --Popski 00:17, 3 September 2005 (UTC)


 * Hey Popski! No I haven't seen the wikitex features.  That's pretty cool!  Thanks for the link!  --Spiderworm 15:23, 6 September 2005 (UTC)