[Bf-docboard] Manual improvement ideas & suggestions.
Tobias Heinke
heinke.tobias at t-online.de
Fri Jan 27 17:11:26 CET 2017
Hello Alex,
1. Workflow
The Manual is not primarily workflow based anymore it's a specification
(UI based).
Workflow descriptions still exist separated under sub-headlines same as
examples.
But isn't a specification in a pure technical sense with all the formal
demands (not following any RFC ####).
The time effort of a workflow based manual is for various reasons way to
high.
Time consuming to write and more important to maintain.
It is out of scope. Even if step by step walktroughs is the industry
standard - that's a luxury especially in form of videos.
(https://opensource.com/business/16/1/scale-14x-interview-bob-reselman).
Unfortunately that leads to "separated chunks of information".
There are alternatives that fill that gab:
Hundreds of videos/blog posts that explain the "basics"
fitting the diverse background of user and what she wants to achieve.
2. Structure
2.1. TOC
There's a search function and links. The full toc has 735 KB - average
is 10 KB per index.
What you propose would be http://getakka.net/docs/?
Don't know what you mean with templates: http://jinja.pocoo.org/docs/dev/ ?.
2.2. Sections
Digital artist workflow = digital production pipeline?
There simply isn't a single workflow/big picture there are a half a dozen.
It worked for years now, no problem showed up.
Even if, planning such big changes take huge amount of time, not even
talking about applying changes.
The non editor chapter are there for:
A) Shared topics between editors (data system, animation, sculpting &
painting) (physics, rendering)
B) To flatten the structure which would be else all in 3D View (modeling).
To give an orientation I added sections descriptions on content.html.
2.3 Semantics:
Discipline or technique that's a semantic like discussion. Practically
it doesn't matter.
Rigging = rigging in Blender.
I disagree about constrains. I guess you based this on a wrong (or
inaccurate) definition of animation.
(wikipedia is not in any way reliable).
and TBH TL;DR
The Plugin:
What you propose is a html select menu that lets the user switch
e.g. the Select Group menu versions for the different object types.
While the content is in the table?
It would be something for a separate website like a hotkey list.
Indeed that's is a problem, but it's solved by hierarchies:
Object mode > edit mode > mesh > curve > surface | armature
Timeline > graph editor > dope sheet > NLA
The reader has to have the ability understand abstract concepts e.g.
replacing vertex with object origin.
Regards,
Tobias
Am 25.01.2017 um 09:45 schrieb 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}
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> https://lists.blender.org/mailman/listinfo/bf-docboard
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20170127/ade802e2/attachment.htm
More information about the Bf-docboard
mailing list