[Bf-docboard] About MediaWiki and DocBook

[Ton Roosendaal]

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-


>
>> I was under the impression the printed manual was a source of money  
>> for the foundation, rather than a downloadable using bandwidth, I  
>> guess coming from your mouth Bart, you would know better than I, so I  
>> stand corrected about print being more important than web.
> Actually, it's both. Ton is paying a share of the bills with the sales  
> of the Blender Guide. On the other side of the equation, having good  
> online documentation stimulates the growth of Blender which, in turn,  
> will also generate more revenue (either through the e-shop or in other  
> ways).
>
> After thinking about this discussion this afternoon it sounds like the  
> Docboard group needs to develop a vision and a mission statement. I  
> usually dislike this crap, especially when my boss starts talking  
> about it. Today though I think it would give us a lot of guidance,  
> knowing that all our actions are contributing towards our vision and  
> that they are in line with our mission statement. I guess the Docboard  
> vision/mission statement (and that of the Webcontent and other groups  
> too!) should be derived from the Blender Foundation vision/mission  
> statement. 
>
> Maybe this would help us formulate our goals and, ultimately, the way  
> we want to work and the tools we want to use?
>
> Bart
>
> (I'll go back to being a webmonkey now ;-)
>
>
------------------------------------------------------------------------ 
--
Ton Roosendaal  Blender Foundation ton at blender.org  
http://www.blender.org