[Bf-docboard] Re: Restructuring Proposal

[Glen Moyes]

>You keep saying "core documentation, theory, tutorials, reference
>material, and so on", but I can't really make out anything more than
>the first three. Isn't the core documentation reference material? Can
>you give an example of "and so on". 
>
I was using the term "core documentation" as the User's Manual as it 
stands now, after we get rid of the fluff and mini-tutorials. I just 
noticed on the wiki that Core Documentation was referring to the entire 
documentation, from the user's manual to references. So, I really meant 
the user's manual, after it's been purified of the fluff and 
mini-tutorials. "And so on" is referring to everything else in the wiki: 
video tutorials, hotkey maps, release notes, FAQ, etc.

>The first thing that comes to my
>mind is the thematic volumes, but these cannot really follow your
>structure. I even doubt that it is neccessairy to put energy in these
>before we have the basic documentation (core, theory, tuts) ready.
>  
>
I don't think I fully understood what was meant by "thematic volumes" 
when I read the discussion on the Wiki. Would it be like having a 
different book just on rendering tricks, another book just on animation, 
and another book just on modeling? That's what I thought was meant, but 
I didn't think it is much different than having the different rendering, 
animation, and modeling sections as we have in the user's manual. Having 
a few volumes like that would be nice for print, instead of having a 
huge tome. That way people can buy things separately. If that's the 
case, I think it's very compatible with what I'm proposing.

>I've also changed my view a bit regarding the in-doc mini tutorials. I
>DO think that things like "modelling a glass" don't belong in the core
>doc's but on the other hand, mini examples should be there. Otherwise
>documenting how things actually work is going to be very hard.
>
Absolutely. I agree. Examples are needed, but anything that breaks the 
flow should be taken out. I think how-to tutorials like the Modeling a 
Glass should be moved elsewhere, but examples on how to actually set up 
a ramp shader, and what each setting does is a must.

>As for final publication (print) we should decide whether to combine
>these volumes or not. If you intend the manual to be that way (first
>theory, then documentation, then tutorials), you should probably
>present it like that too. Experts will have to do with either the
>online version or they have to skip the "unnecessary" parts --
>remember that the book-form is comfortable for those who read the
>WHOLE thing (i.e. beginners), and online docs serve very well as a
>look-up reference. Seperation = quality loss in my opinion.
>
Yes, I wanted each section to be able to flow into each other, as you 
said. It might be better for me to explain that these volumes are not 
stand-alone books, per se, even though they have their own /Manual and 
/Theory sections in the wiki, but are volumes that run in parallel. The 
theory volume isn't written to be read on it's own, but rather in 
conjunction with the User's Manual. Each section in the User's Manual 
will have a link at the top of the page to the corresponding section in 
the theory volume, so that newbies can read that first before proceeding.

Those two volumes are written so that beginners can read the whole thing 
in sequence, while experts can skip the theory parts that they already know.

Don't think of it as "separation" as much as it is clearly marked 
sections, even though they are separate entities in the wiki. In the 
wiki, it'll be marked as /Theory/UV_Mapping, /Manual/UV_Mapping, and 
/Tutorials#UV_Mapping, while in the printed book it will be "UV Mapping: 
What is it?" "UV Mapping in Blender," and "How to UV Map Suzanne," in 
sequence. Same exact content, just accessed in a different way depending 
on the medium. Which is why I'm having them as separate entities in the 
wiki, because you are correct, "online docs serve very well as a look-up 
reference." The new theory volume that I'd like to add is to help new 
users understand what the heck we are talking about, give them a firm 
foundation to build on so that we'll only be confusing them with out to 
use Blender, instead of both Blender and the 3D concept. This would be a 
great addition to a printed book.

Since the theory volume is really just an introduction to theories and 
concepts to every section in the User's Manual, we could simply include 
it right in the User's Manual and no one would think it's out of place. 
However, I also want to include links to tutorials, videos, hotkey 
sheets, and whatever else we want on the same subject in each 
corresponding page in the User's Manual as well, and I think we'd all 
agree that those are very different sections. So I'm linking to the 
theory volume the same way I like to the other resources, just to keep 
things consistent and keeping the User's Manual unbloated.

The User's Manual should be the backbone of what the rest of the 
learning material is built on. People are more interested by what they 
learn rather than how they learn it. I'd like to see users find the 
chapter in the User's Manual, and then be provided with simple and 
concise information on how to do it in Blender (which is the User's 
Manual), and then be provided with links to a chapter on the theory 
behind it, links to tutorials and printable reference sheets, and maybe 
even demo files. That will all be right in front of them, and those 
various sections can be updated independently from each other. That's 
the ultimate goal.

>Another thing, which I want to talk about, is the presets that blender
>comes with. I have seen a lot of people that suggest to newbies to
>switch RMB/LMB & turn on auto perspective... 
>
Honestly, I don't think it will make much of a difference to a new user. 
RMB selects, weird; LMB confirms, not weird. Now if we switch it around: 
LMB selects, not weird; RMB confirms, weird. Either way the user will 
still have to use all three buttons on the mouse constantly, and 
right-click will never bring up a pop-up menu (unless of course if you 
hold it down a few seconds, but that's not the point, LMB does the same 
thing). Understanding when to use which mouse button is something that 
new users will have to struggle with, no matter how we switch it around.

While we are on the topic, there are a few things I would like changed, 
and one of those is the color scheme. I think there isn't that much of a 
color difference between the outline of a selected object and an active 
object. It's too hard to tell there's a difference (especially on a 
projector). Make the active object white instead of a slightly lighter 
magenta, or something.

Also, mouse gestures, the hold LMB or RMB for x seconds to bring up the 
toolbar, and the 3D transform widgets, I would really liked to be turned 
off by default. That is purely in my selfish interests (because I never 
use them), but most importantly it is for my students, who always have 
troubles with those features getting in the way. I had to stop and 
explain what mouse gestures and the 3D transform widgets were before I 
continued on with the basics, because people kept on clicking on them 
accidentally, or holding down the mouse buttons for too long.

Of course we should do a survey with the Blender community to see if 
they would hate those changes. Either way, consistency is a good thing 
between how newbies are learning it, how experts do it, and people that 
write tutorials.

Either way, people can be taught those differences.

- Glen