[Bf-docboard] Blender books -> official reference

[Jason van Gumster]

Hello Ira (and the rest of the list),

Apologies in advance for this long email. :)

If you'll allow me to toss my two cents into the ring here, I think you've
raised some interesting points, but I also think you're making this more
complicated than it needs to be. My understanding of reference manuals is that
the assumption should be that the reader is competent and likely to use the
reference alongside separate documentation of technique and implementation. The
only exception to this would be the notion of a "beginner's reference".
However, I don't think it would be wise for a Blender reference manual to assume
responsibility for teaching users the fundamental principles of each of the
various disciplines Blender is used for. For instance, using your example of
Blender 2.5 Python, the reference should assume that the reader already has a
basic understanding of programming principles (or is getting that information
elsewhere). Using an example that's closer to my heart, reference documentation
of Blender's character animation tools shouldn't have to explain principles
like anticipation or squash and stretch. That kind of information is covered in
greater thoroughness and detail in other texts. A reference manual should
acknowledge these principles and perhaps direct the reader to external
instruction, but trying to comprehensively encompass all of that material in a
single book (or series of books) is well beyond the scope of a reference and
would take far too long to complete (let alone maintain).

That said, the idea of having a series of reference guides is a good one. Like
Ton, however, I would recommend that the breakdown not revolve around user
skill. Instead, I'd suggest that guides be broken down by task/discipline.
Ton's separations appear logical to me, though I would suggest adding another
pair of books in the series: one that's devoted to Blender's rigging tools
(wrapping this in a reference on the animation system is likely to overload
that book with content) and one that expands on the quick-start guide to get
new users up-and-running as quickly as possible (though I suppose the updated
Essential Blender would fill this role nicely).

A comprehensive reference (or set of references) like the 2.3 manual is
certainly something that's overdue for Blender. As for the idea of publishing
something like this on an annual basis, I'm not sure which way to lean. A lot
of it depends on how much changes or gets added to Blender in the course of a
year. Ideally, once infrastructure for this kind of reference is set up,
changes and new features could be updated as they come out, but even with the
current wiki, that's been tough to maintain. Also, if the idea is to go with a
series of reference guides, it raises the following question: will people be
more inclined to purchase a single, massive comprehensive manual or just the
reference guides that pertain to their particular interest/discipline? And will
enough people purchase annually updated versions to make it worth publishing
them?

These are all interesting questions and I would definitely like to be involved
with determining their answers.

Again, my qpologies for the long email! Hopefully it's helpful.

  -Fweeb

Ira Krakow <ira.krakow at gmail.com> wrote:

> Hi Ton,
> 
> Your idea about a Reference Guide is an excellent one.  The problem,
> however, is that one size doesn't fit all.   Everyone has a different level
> of Blender knowledge, so that something one person might think is too self
> evident might be new information for someone else.
> 
> For example, how should Blender 2.5 Python be documented?  If someone
> already knows the principles of OOP, classes, methods, attributes,
> inheritance, and so on, and knows Python, then the current API
> documentation, which lists the classes and methods, is just fine.  If
> someone doesn't understand OOP, or, for that matter, is new to programming,
> the current documentation is insufficient and a reference guide would have
> an entirely different look.
> 
> This principle works with other parts of Blender.  Do we expect users of the
> animation reference to be seasoned 3D animators, or do they need a reference
> to animation basics as well?  The same goes for rigging, lighting,
> texturing, etc., etc.
> 
> I think we need, instead of one comprehensive reference guide, a series of
> guides for different aspects of Blender, geared for different levels of
> user.  The "Noob to Pro" book is an excellent first step to get beginners up
> to speed, but we can't really expect everyone to be expert in all aspects of
> Blender.  So perhaps I'm suggesting a series of reference guides?
> 
> These are just some preliminary thoughts, to start the conversation.  The
> goal is a very worthy one.
> 
> Best wishes,
> Ira
> 
> 
> 
> 
> 
> 
> On Wed, Mar 3, 2010 at 8:14 AM, Ton Roosendaal <ton at blender.org> wrote:
> 
> > Hi all,
> >
> > Writing Blender books for (commercial) publishers is already a good
> > and common bizz nowadays. I can only recommend anyone who is
> > interested in this to contact publishers with good plans!
> >
> > Blender Foundation is also publisher, we did this initially also to
> > open up the market for Blender in bookstores. That's not really needed
> > anymore. :)
> >
> > What would be useful though is still:
> > - have about one book published per year to get additional income
> > - support the current active documentation volunteers
> > - have good quality, open and free docs in wiki.
> >
> > I'd like to get two projects running for this.
> > One is for an updated "Blender Essential 2.5" book, for that I'll
> > first work with the team who has done the first Essential book.
> >
> > Another project is to check on the feasibility for a good (annual?)
> > printed reference guide. Check for example how the 2.3 guide reference
> > was done, I still think a good example of useful reference content for
> > users (includes screenshots etc).
> > Would there be a useful and efficient way to organize this? To get
> > both a great printed book as content for wiki? How? Who? :)
> >
> > Thanks,
> >
> > -Ton-