[Bf-docboard] Manual improvement ideas & suggestions.

[Alex Cham]

Hope that the main goal of the manual is to teach people how to, but not
just to provide separated chunks of information.

Quick guidelines about MUST, SHOULD, MAY - according to RFC 2119, and how
this could be applied in documentation
https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#introduction-terminology



IDEA: TOC improvement. Avoiding Sphinx toctree & templates complexity.

Motivation:
Manual is not to hide information, but to make it easy and quickly
searchable and accessible

Suggestion:
* Make all nodes in the table of contents (TOC) opened by default as the
MUST, to provide ability for browser CTRL+F search when needed.
* Focus on the simplicity of the manual toctree.
* Make theme as simple as possible, avoid templates complexity
* Engage the linearity of the table of contents.



IDEA: Separate manual according to digital artist workflow

Motivation:
Divide And Conquer (DAC). Modeling, Animation, Rendering by themself's are
so complex & fundamental pipelines that it should be very hard or even
impossible to fully describe them and make it easy to follow in single
Reference Manual.

First Things First (FTF). What is needed to understand how to successfully
work in blender? Interfaces & Operations for 3D Space Navigation & Object
Modeling. All other workflows follows only after this first fundamental
constraint is accomplished. When you see the 3rd subsection, it's already
time to think that topic is complex enough to separate it aside. Than more
sections & subsections, then harder to follow...
Example: Editors>3D>3D View>Navigating>Navigation>Rotating.

Terms and conditions (Prerequisites) always goes first, tools/operations
follows, and the techniques finally connects all together and shows how to
apply obtained knowledge.

Suggestion:
Separate reference manual according to digital artist workflow:
(Editors & Interfaces|Modeling|Animation|Rendering)Manual {Glossary,
Operations, Techniques, etc...}

* Editors & Interfaces Manual MUST describe GUI of Editors & Interfaces.
* Modeling Manual MUST describe 3D modeling Operations (Create/Remove
object, Translate, Rotate, Scale, Create/Remove vertex, etc...) &
Techniques (Extrusion modeling, Digital sculpting, etc...)
* Animation Manual MUST describe animation Operations (Create/Remove
keyframe, Create/Remove Action etc...) & Techniques (Rigging, Skinning,
etc...)
* Rendering Manual MUST describe rendering Operations (Change resolution,
Change frame rate, etc...) & Techniques (Ray casting, Ray tracing, Shading,
Texture-mapping, Bump-mapping, etc...)



IDEA: Sortable Table for Blender Operations (Sphinx +
JQeryTableSorterPlugin)

Motivation:
Operations in blender could be described as (Create, Remove, Select,
Change, Copy, Insert, etc...). Objects & entities to which they are applied
are different, but the meaning of operations is still the same. Most
operations have the same properties like Editor, Mode, Hotkey, etc... If
you will need to quickly look which operations could be applied in
particular mode or editor, you can do it easy with sortable table.

Suggestion:
* Make sortable table which will describe the operation itself & all needed
Requirements & Constraints. (HTML + JQueryTableSorterPlugin)
Format could be like:
| Name | Description | Editor | Mode | Object/Entity of Application |
Hotkey | etc...
* Mark operations using semaphore methodology, - (MUST - Red|SHOULD -
Green|MAY - Blue) be learned!

Proof:
https://youtu.be/Yu5VY0JTCIM Sphinx + JQeryTableSorterPlugin integration.
Ready to attach code example if needed.



IDEA: Discipline & Discipline Technique. Sections: Rigging, Skinning,
Sculpting, Compositing

Motivation:
There are no strong division between what is: Discipline OR Technique OR
Operation OR Term OR Interface, etc ... All is intermixed heavily ...

Computer Animation is a discipline and Rigging is it's technique, so
"Animation Manual {Techniques> Rigging}". 3D Modeling is a discipline and
Sculpting is it's technique, so "Modeling Manual {Techniques> Sculpting}".
Computer-generated imagery (CGI) & Video Editing is a discipline and
Compositing is it's technique, so "CGI & Video Editing Manual {Techniques>
Compositing}". Now look at the 2.78 manual layout by the way, with a point
in mind to visually find all sections described above ;)
https://www.blender.org/manual/editors/index.html

Rigging & Skinning are major animation workflow steps and could be even
classified as animation techniques, but it seems strange that Rigging
section moved aside of the Animation section and the Skinning much worst is
inside Rigging>Armatures>Skinning
According to animation workflow it must be, in worst case, at least
something like this:
Animation Manual {Techniques>Rigging|Skinning|Weight
Painting|Posing|Keyframing}

Techniques sections (Rigging, Skinning, Sculpting, Compositing, etc...)
MUST NOT describe Blender editors, interfaces, operations, etc... in
details. They must point out to the concepts of the technique itself and
provide links to the exact Operations which applied in this technique.
Operations themselves are fundamental building blocks which user MUST know
anyway to be able to apply them in Technique. So it's better to describe
them before and separately example:
Modeling Manual {Operations> Create / Remove Object | Select Object ... |
Rotate | Transate | Scale | Join | Create/Remove Vertex | Create/Remove
Edge | Create/Remove Face | etc ...}

Suggestion:
Describe technique fundamental concepts and principals with references to
Glossary and Operations which required to apply while using this particular
technique. "Big picture" video showing the result of this particular
technique (All videos not longer than N minutes).



IDEA: Animation Constraints & Physics Constraints/Kinematic pairs

Motivation:
Animation & Physics, are in fact so complex topics that they deserve to be
described separately and in details.
Somebody will never use pure physics constraints aka kinematic pairs for
animation as the bullet physics engine itself at all.

If to speak about constraints, there are two types of constraints which
MUST NOT be intermixed.
1) Classical mechanics, - Kinematic pair constraints, which are pure
physics.
https://en.wikipedia.org/wiki/Kinematic_pair
2) Rigging constrains aka animation controllers
https://en.wikipedia.org/wiki/Skeletal_animation#Technique
1st type is partially applied to implement 2nd type but 1st type is the
theoretical fundamentals, while second is applied extension of the 1st
type, and logically, information must be provided separately to avoid
constraints hell.
In fact, - there are several animation techniques, at least:
* Physically based animation. Pure Kinematic pair constraints, physical
laws and forces simulations applied.
https://en.wikipedia.org/wiki/Physically_based_animation
* Skeletal Animation. Rigging constrains aka animation controllers applied.
https://en.wikipedia.org/wiki/Skeletal_animation
* Motion Capture Animation. Captured locomotion & Rigging constrains aka
animation controllers applied.
https://en.wikipedia.org/wiki/Motion_capture
* Intermixed Animation. Any combination of the above Techniques or all
applied.
etc...

Suggestion:
* Describe Animation Constraints & Physics Constraints separately to free
users from reading and trying to understand things, that will be never
applied by them.
Blender Animation Manual {Motion Control>Constraints}
Blender Physics Manual {Motion Control>Constraints}
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20170125/418dc5f2/attachment.htm