[Bf-docboard] Blender Proceedings

[mindrones]

On 11/13/2010 05:11 AM, Raindrops From Sky wrote:

> *The worst-case scenario (assuming there is no resource-allocation for
> documentation):*_
> 1. We simply accept Mont29's suggested new TOC. No more dithering on
> that one.

Bastien's big work is on my todo list from too much time, I agree, but 
this doesn't mean it has to be accepted without reviewing IMO.

Bastien work is something which changes a lot of pages and linking, so 
it's not something you can undo easily. This is why I believe someone 
experienced with wiki has to review it (it doesn't have to be me btw).

I've thought many times about mail him and say, "just go ahead, put in 
the Manual", because I trust him. But I'm also a big fan of peer 
reviewing. IMO if we start accepting every big chapter rewrite as it 
comes, just because we don't have time, then we don't know where it 
ends, especially if we do a spaghetti of the links history to a point 
where you can't get back to the previous situation.

Marco makes backups, ok, but as he said once, this doesn't mean we can 
do whatever, because takes time to restore a backup.

I had planned to start reviewing the Modeling chapter after the 
conference, hence I think I'll do that this week as a start.
The Animation part will come later.



> 2. Translations are out. We stick to English.


No way. There is really no need to do that, because it doesn't affect 
the english manual. Translations can very well be out of date and it's 
not harming. Right the opposite: someone will be disappointed and will fix.

Try asking Greylica what he do think about deleting Doc:BR/Manual if you 
dare :)
It took 1 year translating the whole manual.

Or ask all the people who can read the old but still almost-valid manual.


> 5. We split the work (e.g. I can quickly take various screenshots of
> Blender and upload them all in a folder.)

One takes screenshots to say some specific thing, not previously.

If you are talking about screenshots for buttons and menus etc, has no 
sense to do it by hand, because things change too quickly. You would get 
a lot of screenie sitting there doing nothing until they get old, this 
thing has to be done automatically in a way that updating the whole 
manual is quick and easy. There are plans for that too.


> 6. Link to videos only from individual topic pages of the wiki. No more
> showcases (what Andrew made recently)

Video is ok, but it's fluid information: you can't select content, 
search for it, copy paste it, and especially it gets old quickly.
I would be against having a massive video manual.


> Frankly, the structure seems too complicated to me.

It is linked from the main guideline
http://wiki.blender.org/index.php/Meta:Guides/Writer_Guide

see
http://wiki.blender.org/index.php/Meta:Guides/Blender_Wiki_Structure

The are reasons for such a structure:

1)

mediawiki doesn't have the concept of "folder", but understands foo/bar 
to put the so called breadcrumbs up in the page.

For example, in
http://wiki.blender.org/index.php/Doc:Manual/3D_interaction/Manipulation/Pivot_Points
up in the page, you have:
< Doc:Manual | 3D interaction | Manipulation
so you know where you are. This is impossible in a flat wiki.

2)

You can list subpages like this
http://wiki.blender.org/index.php/Extensions:2.5/Py/Scripts/File_I-O
with the appropriate template

3)

A lot of templates are now kind of "smart", because they rely on a clear 
convention with pagenames (a "structure").

For example the navigators rely on that to work automatically.; 
previously, you had to do a lot by hand, which resulted them being messy 
and not homogeneous.


> Rather than
> struggling with legacy issues, can we have a plain vanilla mediawiki+pdf
> export extension? (Drupal is also fine IF someone is ready to handle the
> complications)

Again, you are talking about admin stuff: see my previous mail, there is 
a practical reason if things aren't moving on that side.


> Wikify everything (no plain web pages),

?
> and throw it open to volunteers.

??

> Admin will have to handle creating new pages whenever anyone requests.

???

> Then we can create a new TOC starting at top, and create branches for
> UM, API docs, etc. Leter port whatever we want from the existing site,
> and then decommission it.

.....


> BTW we should know what decisions were taken at the Blender Conference
> 2010.

It was a roundtable, a way to discuss problems and solutions.
No decisions.


--

All in all I'm not sure I will reply again just to remark things that 
are already well known here, it's a big, big time sink for me :(

The main points have already been pointed out and discussed.
In the next weeks we'll see what happens; as said it depends on the 
chance the BF has to setup a secure server for wiki, in order to let 
admins work on it and move things on.


If your main concern is content, well Do it!
There's a whole Sandbox happily waiting for you :)


Regards,
Luca

_____________________________

http://www.mindrones.com