[Bf-docboard] Blender Reference

[Tony Mullen]

Hi Pep,

Congratulations on your efforts. You seem to have covered a lot of
material. As you mention on the page, you began it as a notebook of
what you were learning, and as such I think it clearly shows you
learned a lot doing it.

>> hard work ahead, the writing, etc. is not a problem. What is really
>> exhausting is to try to find out how everyting works: some buttons are
>> not implemented; others have buggy behaviour; others are difficult to
>> see how it goes...

Yes, it's not realistic to document all of Blender exhaustively all by
oneself. But a whole lot has already been documented to greater or
lesser degree on the wiki and can always benefit from updating and
broadening. You mentioned that you might re-focus your attention on
contributing to the official wiki, which I think would be a great
idea.

>> I agree what I need would be to meet regularly with some patient
>> developer, and steal a huge amount of time from him, but their time is
>> very valuable, and I'm not sure they would reckon it's worth spending
>> it with me.

This wouldn't really solve the problem for a couple of reasons. The
biggest reason in my mind is that no single developer knows everything
about Blender. Of course many of the busiest ones have a very good
overall understanding of the code, but for the level of detail you're
talking about---what does this parameter actually mean on fluid, and
what does that check box do on an f-curve driver, and so
forth---honestly there's no single person who knows all those answers
off the top of their head. Or at least there are precious few, and
they're very busy with other things.

That said, I've always found developers in the IRC happy to answer any
detailed questions I have, if I can manage to catch up with the
*right* developer who knows the specific functionality I'm asking
about. But that often takes a bit of lurking.

I also think that there's a limit to how detailed, up-to-date,
accurate, and deep user documentation can be for any given release of
Blender. As you said yourself, there are buggy spots, sometimes
slightly incomplete or temporary bits, and it's all very complex and
changes rapidly, and so it's extremely difficult to document some
frozen moment in time perfectly. And even if you could, it would
change again quickly. Any serious user of Blender has to understand
this and be able to work with it.

> A developers time is COMPLETELY wasted if they program something and
> no one can use it because no one has bothered to put it in the manual!

This isn't quite true. I think that the most skilled and frequent
users of Blender actually do a great deal of work with features that
aren't well documented for beginners. One thing these users do is
develop working relationships with developers who work on the
functionality they use most. So, for the real power users, this kind
of documentation is not that important, but the functionality is very
important to them (whereas less experienced users wouldn't be able to
do that much with the functionality even if accurate and detailed
beginner's docs existed).

This isn't to say documentation isn't important. It is. But the
functionality is more important, and developers aren't wasting their
time by focusing on it. And although beginner/intermediate
documentation is important, there are a lot of features of Blender
that simply *aren't for* beginner/intermediate users. That is to say,
there are values and options that simply don't make sense to people
who don't have a fairly deep understanding of what they're doing. So I
don't think beginner documentation of some of these details is a high
priority.

In any case, the place for an exhaustive list of all the buttons and
fields is a communal wiki, for sure. No single person could write it
all, much less keep it up-to-date for five minutes. Blender
documentation is a Sisyphean task. It's important to feel like you're
learning something or having fun doing it, or else it will overwhelm
you.

T