[Bf-docboard] Getting involved & NEW FORMAT

[Ewout Fernhout]

Hello,
 From what I understand, the documentation project is going to move on 
to a new format, because the CVS + Docbook system is not very accessable 
(...). So don't bother with CVS or Docbook, just write down what you 
think should be changed and/or added. Post that to the list.

While I'm at it... I seems that all discussion seized after Ton's strong 
post, whereas I think it should've inspired us to continue to search for 
a new format. With the upcoming 2.40 release and the manual with it, we 
should not wait too long to make a decision!

I'll continue with a quote from his post:

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

1) This is perhaps a question that's not well defined, so I'll answer it 
in a broad sense, because I think there's a difference in editing access 
and reading access.
*Editing access:*
This should always be done online I think (it needs to be submitted 
anyway). I read that there are some people that prefer to create a 
document (offline) first, and upload it when it's finished. Although it 
may be possible to be able to create documents offline, upload them (as 
a file) and then edit them online, it's not very difficult to copy/paste 
into an online editor (which makes the system a bit less complex). This 
way small edits (like grammar) don't require you to upload a complete 
document. When a user is reading the docs online and discovers a mistake 
he/she can easily edit by just pressing an 'edit' button, it's more 
likely to happen than when he/she has to open the corresponding document 
in an editor to change it and then upload it again.

The format should be as easy as possible. Because the document needs to 
have some sort of format (confusing word, I mean layout/font format 
now), the user has to be able to set these things. I think it's pretty 
hard to avoid using tags for this, but a WYSIWYG editor would be really 
nice! If WYSIWIG is not feasable because of cross-browser issues, then 
at least there should be buttons that generate tags the way it works on 
a lot of forums now-a-days. In any case, a lot of users who will be just 
helping with spelling & grammar or other small things won't need that 
much tags because the basic structure/format is already done.
Another thing: being able to revert to a previous version can be very 
usefull in a case of disagreement (discussed further below).

To refer to wikimedia:
Apparently there are several (working!) online WYSIWYG editors for 
wikimedia, see
http://meta.wikimedia.org/wiki/WYSIWYG_editor
or http://www.fckeditor.net/demo/default.html for a demo

also, all wikimedia sites (including wikibook) use a toolbar for the 
most common tags (check http://en.wikipedia.org and hit an edit button 
somewhere)

*Reading access:*
Reading, of course, should be both online and offline. BUT, it is 
important to inform the offline reader that a newer, more up-to-date 
(better) version may be online, and that online reading is always 
advised. Having a flexible system like wikimedia, where several 
(dozens?) edits can be done in one day, which is exactly what can make 
it a very good documentation.
HTML is probably the best standard because it doesn't require a specific 
reader (an HTML browser comes with every system that runs Blender I 
think), as opposed to PDF. On the other hand, a PDF is more suitable for 
print (I'm not talking about the book but the printer attached to your 
computer), and most people have a PDF reader on their system aswell.

So in short, when the editing is being done online, there should be an 
easy way to download sort of 'nightly builds' of the documentation in 
either PDF or HTML. These should contain a direct link to the up-to-date 
online docs or at least a notice.

referring to wikimedia again:
There is a wiki2pdf project:
http://sourceforge.net/projects/wikipdf/ (yay, Python :o))
and ofcourse, exporting to HTML is quite simple, which would be a 
collection of the pages you get when you press "printable version"
http://en.wikibooks.org/w/index.php?title=Blender_3D:_Noob_to_Pro&printable=yes


2) What format pleases motivated (active contributing) authors best?
It's hard to say what's motivating active contributing, but I'll have a 
try at my own definition. I believe it's motivating when the tools don't 
obstruct you in any way when you're writing (or rather demotivating when 
the tools are hard to learn or limited). That's one aspect.
Another important aspect is seeing that your work is appreciated. Some 
people like to be credited, others like to see feedback. I think both 
options should be there, the first of course determined by the people in 
charge. Feedback is also in the form of edits in your document. When you 
see that people help to improve the document, that's a good thing. On 
the other hand, it's a danger. Not so much of abuse (there are many ways 
to prevent this), but rather of different points of view. When you have 
worked on a certain document for a long time, and you see that people 
change it in a way that you don't like, that can lead to serious 
disappointment in the system. After all, it was 'your' document.
I believe this can be avoided by having a system that allows room for 
discussion on every document. That way, when someone radically changes 
something, it can be discussed and reverted when necessairy. Then at 
least the primary contributor is involved in the process (or left the 
option to involve). I also believe that this attitude to the document 
should be discouraged: if you want to have active involvement in the 
docs, everyone 'normal' editor should have the same rights: he/she does 
not own the document. Only when people are open to changes the document 
can progress and become better.


All in all, I believe wikimedia is very well suited for this task. I 
have worked on and created a few documents at both wikibooks and 
wikipedia before, and I enjoyed it a lot. It's quite easy and I have yet 
to see a better system for online cooperation on documents. If anyone 
can come up with good alternatives, I'd love to see it.

Ewout

Olivier SARAJA (Linuxgraphic) wrote:
> Hi,
> 
> welcome to the Board.
> 
> for information about getting involved, you should check this link: 
> http://www.blender.org/cms/Get_Involved.233.0.html
> and more accurately, this one:
> http://www.blender.org/cms/Documenting_Blender.226.0.html
> 
> The rest is a matter of skills. I don't have myself skills with CVS or 
> DocBook, but it should not prevent me from keeping myself involved anyway! ;)
> 
> Cheers,
> olivS
> 
> Le Samedi 27 Août 2005 00:06, Keith White a écrit :
> 
>>ok, i'm fairly new to blender, and as such, i'm working through the docs.
>>I want to get involved with helping keeping things updated. Or perhaps
>>adding stuff of my own as i get the grasp of operations figured out.
>>so, what do i do now ?
>>
>>formats ?, cvs ?, procedures ?, etc
>>
>>cheers.
>>Keith White.
>>
>>
>>_______________________________________________
>>Bf-docboard mailing list
>>Bf-docboard at projects.blender.org
>>http://projects.blender.org/mailman/listinfo/bf-docboard
> 
>