[Bf-docboard] Bf-docboard Digest, Vol 44, Issue 4

[Jean Montambeault]

Roger Wickes a écrit :
> Hi everyone! I just got the digest, and am glad to see some interst, 
> so I thought I would add my $0.02 to direct some effort.
> Regarding:
Great! I was just about to send you  a message although I am not 
surprised to see you since your contribution to the Wiki is the greatest 
since Stefano's years.
>
> > For myself I've always felt that the documentation should have many
> > parts (books):
> > - one for quick reference where an experimented artist could find a
> > precise description of the use of every feature ;
> > - a manual that would elaborate on the reference to make every sticky
> > point clear, give clear examples where needed and cross-reference to
> > the rest of the Wiki;
> > - a collection of tutorials that would go further than the basics, not
> > just repeat in an informal way what can already be found in the
> > reference or the manual.
>
> There ARE three books:
I know that. I was just expressing my opinion with its nuances.
> wiki.Blender.org/Manual - descriptive, end-user, elaborate
Too elaborate sometimes. Much of the stuff on your page on UV mapping 
should go in a tutorial IMHO. As good as it is, it breaks the rules of 
concision that were established for the manual. Your page on the ramp 
shaders is, to the opposite, perfect. I hope that you won't take my 
criticism in bad part : it is difficult for me to do since I am not one 
who likes to criticize but I believe that it is necessary that we start 
this new effort on a sound, hence honest basis.
> wiki.Blender.org/Reference - specific, precise, detail
I'd add that it still has to be written in user's language, not in coder's.
For example, on 
http://wiki.blender.org/index.php/Reference/Panels/Editing/UV_Calc
this : "

    * Calculation Method

    *Angle-Based* - unwraps by following faces until the angle of the
    face causes a 'break' which results in an island. 
"

It is of no use whatsoever to simply describe the algorithms to the user.
IOW, the reference should express something that will make the user 
better use Blender.

> wiki.Blender.org/Tutorials - workflow, start-to-finish, step-by-step 
> accomplishment-oriented
And it is a great resource, never publicized enough IMHO.
>
> Each book is structured at a high level the same for consistency.
There are drifts in the manual, as I described.
> So, if I want to know what Blender can do regarding Materials, I flip 
> to the Manual book, Materials section. If I want to know what a 
> specific panel control is/does and maybe the math behind it, I flip to 
> the Reference book, Materials panels. If I am completely lost 
> regarding how to color my cube, I read a Tutorial book Materials section.
I'd say that it is mostly usable : I have very little problem finding 
anything myself... inasmuch as it exists. Understanding what's written 
is another matter sometimes and being able to make use of what I find 
still another, sometimes.
>
> All wiki books are listed on wiki.Blender.org, so..maybe you want us 
> to say what I just said on that page, or provide a "Guide to using the 
> Blender Wiki Books" page?
Don't you find the first page of the Wiki to be a total mess ? I do but 
that shouldn't be our concern here, as long as the visitor can find 
his/her way quickly from there to the documentation books. One simple 
but unmistakable link to the Documentation that would lead to a page 
that would then link itself to each of the three available books, with a 
short description of what they are.
BTW, I feel that we should regroup /all/ the available documentation 
under one of these books. For example I see no reason for which the 
ageing BSoD tutorials should be kept off the Tutorials book.
>
> The list of Manual pages that need updating, for those new to the doco 
> effort and want to help, is also ont he wiki.Blender.org page, but is 
> specifically http://wiki.blender.org/index.php/Wiki_Taskswhich i keep 
> updated for each Blender release for changes needed to the Manual 
> book. If someone else wants to augment that page with deficiencies in 
> the other books, go for it. Of course, if anyone sees any issues with 
> any Manual page, please update that to-do list!
>
>
> > - ideally we would have our own introduction to 3D graphics, animation
> > and real-time because not everyone has a mastery of the lingo in use
> > among 3D artists. I guess that I am dreaming...
>
> You are dreaming if you are expecting our intro to 3D graphics, 
> animation and real-time book to be available free of charge. There are 
> entire sets of books in libraries that cover those topics most 
> completely, or available from Amazon, or schools (Animation Mentor) 
> and various web sites that provide very useful information, including 
> some threads in BlenderArtists. Previous/current wiki attempts are 
> marginal at best. With our limited resources, we need to keep Blender 
> documentation focused on using Blender specifically. (Scope Control!) 
> and try to keep the three books up to date: Manual, Reference, Tutorials.
First I want to underline the point that I agree that the documentation 
in other books is the priority.
Although much can be learned by the ways you suggest, I still think that 
you underestimate the importance of a general introduction to 3D 
graphics of our own. Blender is and will remain an entry point into that 
domain for a long time, at the very least. Many, maybe a majority, of 
newcomers are fairly ignorant of the basis of CG. Moreover the concepts 
of CG , as they are reflected in Blender, are disconcerting even to 
seasoned pros ; them as well as the absolute beginners may find that a 
library knowledge doesn't apply very well, unless we make an effort to 
correlate the general concepts of the trade to what is found in Blender. 
Such an approach is present for Maya and Lightwave, to my awareness.

I know that many present users and coders don't want to endorse that 
responsibility and wish that Blender would return to the "exclusively 
pro" roots that it had at the beginning, although maybe none would 
express it so frankly. Yet I feel that this is a responsibility that we 
can't avoid.
 
I also can't forget that hobbyist and gentleman blenderers were for the 
most part all that Blender had to survive on when came the time to save 
it in 2002.