[Bf-docboard] Blender Manual: Vision Statement

[Tobias Heinke]

Hello Ton,

But it's like removing the tooltips and then declare everyone has to 
know B. before using it.
Less work to write tooltips frees time for more bug fixing, thus results 
in a better user experience - right?
Not finding something in the manual is like when B. crashes or a missing 
feature. That bad, but what should count is the average UX.

I'm not happy with the new rigging page: Lists are super unpleasant to 
read and it's an overview - summaries of subpages (see previous mail - 
other thread).
Especially the 'mixed editors' chapters need a proper intro.
I agree that some of the intros are not in good shape, but that's not a 
bigger problem than with any other kind of doc:
References are less free and fixing issues there has simply a higher 
priority.
e.g. the examples at the Math Node 
<https://docs.blender.org/manual/en/dev/compositing/types/converter/math.html#examples> 
and the Mix Node 
<https://docs.blender.org/manual/en/dev/compositing/types/color/mix.html#examples>.
I agree that lengthy intros should be made more condense.
But the methodology should be just lowering the priority and "fade it 
out"/discontinuing it by not creating any new ones.
And clearly not to plainly deleting them - like tearing down a half 
build building.

I don't know what should be more fundamental in animation than keyframes.
And I don't get why it may be confusing. The definition of a keyframe as 
a point in time linked to a (discreet) value
might be overly wide, but it's correct and it's also called that way in 
the UI.
The curve defines the interpolation between the keyframes mathematically 
represented as curve points.
Accordingly the points in the Dope Sheet are keyframes.

With the "designer" view point you mean programmer (software designer) I 
guess.
If you're generally tech interested it might be suited, but not for artists.
Or do you mean functional descriptions 'hit the button this will happen'.
But that's only one of several types of doc with it's advantages and 
disadvantages.
The latter have to be addressed by applying other types that serve better.
It's the task of a user manual to explain how to use something without 
having to struggle with the "inner workings".

Blender in context of CG vs. Blender's quirks ;)
There is no B. specific big picture, but common CS/CG methods.
The latter is not how good doc works. It should start with the familiar 
(or fill it in), then add details and point out differences.

CG has such a wide range of disciplines there isn't a single knowledge base.
e.g. if one just does modeling plus 3D printing and not animation.
Then there arises the problem what is considered basic, this will lead 
to troublesome inconsistencies.

This would have serious consequences and thus have to be handled with care:

We shouldn't forget who the audience is and who is willing to write it.
Ultimately the manual will turn from a primary source into a secondary 
source:
Blogs and video tutorials, etc. which then transfer it into user 
friendly content.
The result will be a step to pure reference and will turn out bone dry 
and boring to read/write.

Regards,
Tobias


Am 11.12.2017 um 17:57 schrieb Ton Roosendaal:
> Hi,
>
> Dropping age mention altogether is fine. Bastien's wording feels fine 
> for me:
>
>   * People educated on CG, who already understand the basics of 3D
>     and/or know other 3D software.
>
> Tobias: it's especially the beginner-based pages that made me propose 
> the manual focus. I noticed some disappeared already (like the rigging 
> page), which is nice. But it's still weird in places; for example this:
>
> https://docs.blender.org/manual/en/dev/animation/keyframes/introduction.html
>
> "Keyframes" is not a good first mental model to explain how Blender 
> animation works.
>
> Same here - is confusing.
> https://docs.blender.org/manual/en/dev/animation/actions.html
>
> Blender works with Actions, which have channels, and these have 
> curves. The curve consists of points, usually Beziers.
> The term "inserting key" means you insert a bezier point with handles 
> in a curve in a specific channel. These points get visualized as keys 
> in dopesheets.
>
> Explaining Blender from the point of the designer (how it works) will 
> lead to much less confused users, and to much better understanding for 
> mastering it without reading a manual all the time. That's why I 
> suggested to also focus on presenting the big picture, to make people 
> understand the inner workings in general.
>
> -Ton-
>
> --------------------------------------------------------
> Ton Roosendaal  - ton at blender.org <mailto:ton at blender.org>   - 
> www.blender.org <http://www.blender.org>
> Chairman Blender Foundation, Director Blender Institute
> Entrepotdok 57A, 1018 AD, Amsterdam, the Netherlands
>
>> On 8 Dec 2017, at 19:20, Tobias Heinke <heinke.tobias at t-online.de 
>> <mailto:heinke.tobias at t-online.de>> wrote:
>>
>> Hi all,
>>
>> It should be a credo/creed - it doesn't have to be accurate or even 
>> realistic. It's what we try to achieve (in a perfect world).
>> And about what makes the manual different from other source of info 
>> about B. The aim should be one condense sentence.
>>
>> I generally like the current mission statement, but what about 
>> replacing the "you" with "readers".
>> It's an info for people who hopefully become contributors and not for 
>> the readers. Also the triple "to" should be addressed:
>>
>>     "This manual aims to be a complete and concise source of 
>> information to help (the) readers (to) become familiar with the 
>> application."
>>
>> About Ton's remarks:
>> The described target group is/should be only the core audience. (as 
>> already pointed out)
>> An age is only a codification of certain skills reached (by school 
>> edu.) with ~18: advanced math & physics and basic computer science.
>> Expecting basic 3D is contrary to the current situation. We explain 
>> the basics e.g. what an edge, face, or a keyframe is, but not 
>> advanced/expert topics.
>> The "internal (technical) design" would mean data-blocks, dependency 
>> graph? such topics are currently barely covert would be
>> only of interest for experts and add-on devs. That would be on the 
>> edge to code documentation.
>>
>> Regards,
>> Tobias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.blender.org/pipermail/bf-docboard/attachments/20171215/40dbfe6a/attachment.html>