[Bf-docboard] Re: Restructuring the documentation

[Jean Montambeault]

----- Original Message ----- 
From: "Glen Moyes" <metsys at icubenetwork.com>
To: <bf-docboard at projects.blender.org>
Sent: Tuesday, December 13, 2005 2:13 PM
Subject: [Bf-docboard] Re: Restructuring the documentation

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

Finding out what the hierarchy is among the Ways To Blender will proove to
be quite an exercise. What would be the criteria and from whose point of vue
? That could be very counter-productive. I'd think that the more objective
criteria of 'Core' vs 'Tutorials' to be more efficient.

>
<snip>
> I've come to know
> that students need to understand every way of doing things, even though
> they'll never use that method again.
<snip>
<> 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.
<snip>
>. 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.

Doing just that is going to be quite an achievement. If we succeed though
there are chances for the documentation to reach a more stable state.

>
> 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.*
>

I like your views quite a lot. One point though : the entry point of all
that incredibly vast documentation has to be a tutorial, one that'll explain
how to best use the documentation. ;)

>
> As for restructuring the documentation, I'm all for it....
<snip>
>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.

Nice esposé Glen. Hopefully this will be followed by some action.

Thank for sharing your experience and considerations.

Jean