[Bf-docboard] Re: Restructuring the documentation

[Glen Moyes]

>While I was translating the Manual to French http://mediawiki.blender.org/index.php/Manual.fr/PartII/Mode_Objet
>I was struck by how muxh even a matter as simple as moving an Object may have become complex ! So many ways and consequences... Way too much to encourage newcomers IMO. I am not a person to dwell into difficulty if not necessary.
>Discussing with people on Elysiun the idea of a barebone documentation slowly took form in my mind. Kind of a minimum knowledge to survive in Blender. This could be the object of the first sub-section of any subject, while the rest would deal with alternatives and detailing the less used commands.
>This also could be an answer to the need for re-organizing the documentation as expressed in http://mediawiki.blender.org/index.php/Meta/Restructuring_the_Manual :
>at the core an easily maintainable barebone documentation  (since it would stick to the most fundamental and enduringtechniques)  would introduce Blender as a whole in the simplest manner possible which, I believe, is greatly needed, and specialized volumes (on modeling, shading, lighting, rendering, post-production...) could document in depth every aspect of the workflow.
>
>Is this interesting enough to start the discussion ?
>

One thing we did discuss here is separating the core documentation and
tutorials. The documentation has been full of little tutorials that ruin
the pace for power users and CG veterans who are switching applications.
Doing something similar with "the preferred way" and the "other ways" of
doing things in Blender is a valid thought. The trick is trying to
figure out how to organize the core documentation so that information is
not hidden. Maybe the less preferred ways (like using those silly 3D
transform widgets to move objects) could be the last method listed in
the Moving Objects section.

Just something to remember: After teaching 32 hours of Blender workshops
(I'm not bragging, just letting you know I have experience with how
people actually learn this software besides myself), I've come to know
that students need to understand every way of doing things, even though
they'll never use that method again. Moving objects is a good example of
this, which by an odd coincidence is also the example you gave. They
need to know what the 3D transform widgets are right off the bat because
they are on, and in the way, by default, and if they accidentally click
on them (which always happens) they will get confused and want to know
what the heck they did. Usually that is pretty simple for them to figure
out on their own because it's something they physically clicked on, and
then they'll promptly ask how to turn the widgets off. But there are
some unseens that most users will accidentally discover. In the first 2
hours of telling students how to move objects, almost half of them
accidentally left-click and dragged which put them in grab mode
automatically, or some other transform mode, by using gestures. They had
no idea that feature was in there. I wasn't planning on teaching them
that, because I never use it, but they needed to know what it was so
that they could avoid it. Same goes with holding down the LMB or RMB for
a few seconds. They simply need to know these things.

The point I'm trying to make is that even though pressing R, G, and S is
the preferred way to enter transform modes, they need to know the other
two ways so that they'll understand why Blender is acting the way it is.
People have an amazing ability to stumble upon even the most obscure of
features, and it is better to be taught those things right away, rather
than being confused and frustrated. Spending that extra time teaching
all those ways is not that much more difficult or time consuming,
because ESC still cancels, LMB still confirms, SHIFT and CTRL still ...
and so on, and it's easier to explain those things while you are already
on the topic, and it builds upon using the hot keys.

Now, that is the most extreme example of that problem, and it's a big
concern because it happens so early in the learning process. We could
probably get away with explaining the preferred ways of skinning, and
then talk about the deprecated ways which still work later on in the
documentation. The core documentation shouldn't contain ONLY the stuff
people actually use. The core documentation should briefly document
EVERY nook and cranny of Blender, and in an order that makes sense and
is easy to search for everyone.

We should also separate the theory and concepts from the core
documentation. Newbies who don't know what UV mapping is should be
taught, in a friendly way, what it is and how it works. People who are
already using 3D software know this stuff, and can just skip that
section and go right onto the tools. That kind of separation is a good
thing.

This is how things should be taught, in my opinion (at least this is how
I felt it was the most successful): Theory > Tools > Examples.

Newbies need to first understand the concept and the terms. If they
don't get this, then there's really not point in going forward (most of
the people that I've taught had problems understanding the instructions
they read on line because they don't understand all of the
program-specific terms and theory behind it). Then you go right into the
tools. Just explain the tools. Use an example if you need to (it's kind
of hard to show rigging if you don't actually have a model to begin
with), and then after that you can go into more in depth examples, in
other words, tutorials.

I think that is how the documentation as a whole should be set up. Have
a separate set of pages for theory, core documentation, and
tutorials/resources. The top of each page in the core documentation
should have a link to the corresponding page regarding the theory of
what is about to be discussed. The bottom of each page in the core
documentation page should have a link to the page for tutorials, videos,
and other learning resources on that same topic. The other theory and
tutorial sections could also have similar cross-linking between those
pages on the same subject.

That will give new and current users a lot of freedom to search for
different information on the same topic.

As for restructuring the documentation, I'm all for it. I personally
think that Lighting should be taught before Materials, and the way
animation is split up in the documentation is a little annoying for me
to search. So a little bit of reorganizing would help. And I like the
idea of doing it loosely by process. We just need to make sure that each
segment of the documentation, both Theory, Core, and Resources, should
be organized the same way so that cross-linking will be easy.

- Glen Moyes