[Bf-docboard] Blender automatic reference design

[mindrones]

Hi all!

With the the massive wiki upgrade done (and after the some rest :),
finally we have started to design the Blender automatic reference.
Based on the old proposal made in March 2010 [0] and after many many
months of discussions in #blenderwiki, we would form a small team [4] to
work on the points below:

Short term
-------------
* automatic documentation of all GUI items [1]
* reference integration into Blender [2]

Medium term
-------------
* reference editing inside Blender [3]


If you want to read more about each point, see below (coding details are
not included in this proposal by purpose, to avoid to adding too much
complexity to the discussion).

There were other 2 points we discussed but those might seem pretty much
too ambitious for now, so we'd like to see where we can go from here,
and decide later on :)

We hope to hear some good feedback, in order to spot problems we haven't
seen, which would help us in designing a solid Blender Reference.


Regards,

Luca Bonavita (mindrones)
Bastien Montagne (mont29)
Francesco Siddi (fsiddi)


---


[0] FORMER PROPOSAL
--------------------------------------------------------------------------------

http://wiki.blender.org/index.php/User:Mindrones/Wiki/Proposals/2010



[1] AUTOMATIC DOCUMENTATION OF ALL GUI ITEMS
--------------------------------------------------------------------------------

For each GUI item we intend to automatically extract as much information
as possible from the Blender code, namely:

* type (panel, button, menu, ...),
* label
* tooltip
* shortcut
* called operator

and design the information so that users can add:

* usage example
* faq
* gotchas
* used algorithms/formulas
* python snippet

All these blocks of information would be formatted as wikitext, using
ad-hoc templates/js/css in such a way that wiki writers can
transclude/reference them in other wiki pages (manual, tutorials, ...).



[2] REFERENCE INTEGRATION INTO BLENDER
--------------------------------------------------------------------------------

We are planning to integrate this information back in the Blender's GUI,
so that it is presented in expanded tooltip similar to those you can see
doing a Grab and then pressing F6 in the 3dview.

As an example, if a wiki writer provide a small usage example for a
constraint type, we aim at presenting that small usage example, for now
as text, in the expanded tooltip.

This would be especially useful in cases when trying an option ot see
what it does is destructive; for example in Physics usually any change
destroys the cache, so you wanna know well bofore what an option does,
and often the tooltip itself is not enough, is missing, or it's not
enough clear.

At this stage the workflow would be:

* editing the reference in wiki
* reviewing
* commiting good stuff in Blender's code



[3] REFERENCE EDITING INSIDE BLENDER
--------------------------------------------------------------------------------

The workflow suggested above is not very easy indeed.

At some point we would like to have these expanded tooltips editable
from within blender, in such a way that:

* the user finds a typo, or missing doc
* he/she edits or adds an info
* this would be saved in a local file, that can be sent to the wiki or
to a webapp for reviews
* again, the reviewed information would be included in blender's code,
but also in the wiki reference


We believe that by having the chance to edit the doc from within Blender:

* the user would not have to open a browser while he/she's working,
which is distracting
* there would be no need learn mediawiki syntax
* the user can contribute just for small parts, even just for one button
in his own life, but this can be useful
* makes the user feel part of a community
* we would get help from a lot more people.


Proof of concept
--------------------

In the past months, we placed suich a tool in the Blender menu called
"Submit description", that sent data to an experimental blog that
collected this users input.

See: http://www.mindrones.com/blender/svn/

In a few months we had 6386 contributions, all from within the Blender's
GUI.
This is a standard blog, and it's easy to categorize and automate this
tool to cleanup from spam, or repetitions.

This should demonstrate that it's not impossible to get this kind of
stuff from random Blender users.



[4] TEAM
--------------------------------------------------------------------------------

* Luca Bonavita
* Bastien Montagne
* Francesco Siddi
* If this proposal will have good consensus, we will need help from
Campbell Barton.