[Bf-docboard] About the last e-mails received in the bf-docboard list.

[Jason van Gumster]

It took me a while, but I'd like to poke my head in on this conversation...

Raindrops From Sky <raindrops.fromsky at gmail.com> wrote:

> Assuming more than two people write about one topic in their own sandboxes,
> reconciling them would be a big task.  It is better to adopt the stubs
> approach.
> 
> In fact, having visible stubs is good, as it prompts people to come forward
> and contribute.

The point is that stubs *haven't* worked. In fact, if I may be so bold, part of
the reason for the initial wiki overhaul was because the "wikipedia approach"
_wasn't working_. It ultimately lead to a lot of dead ends and outdated
content... and the only people who were aware of that were mostly new people
who were unable to fill in the blanks and update the content themselves.

Now, as I stated at the Blender Conference documentation roundtable, the
current solution is, in my opinion, a bit over-engineered and doesn't
necessarily make it easy for writers (and maintainers ;) to contribute. With
clear communication (on IRC and on this list), the sandbox approach is clearly
a good choice for maintaining content at a suitably high standard. However,
the guideline "tome" presents a somewhat large barrier to entry (documentation
on 'how to document', if you will). I'll try to present some solutions to this
in a future email, but I do believe we're on the right track.

The community is very nicely filling the void in terms of new user introduction
and tutorial-based content. What doesn't exist in a clear fashion are
comprehensive references; specifically, three types of references:

  1) The 'what does this button do' type of reference, which can be automated
     to some degree. However even that generated content should be subject to
     editing and refinement.

  2) A workflow reference (e.g. "How does one texture an object"): not as
     specific as a tutorial, but covering subject matter that spans multiple
     parts of Blender's interface.

  3) A developer reference covering Blender's architecture and processes for
     modifying and extending Blender.

Each of these things *are* currently being worked on, but this sort of
reference material hasn't necessarily been the focus of the Blender wiki and
content has too often drifted into the realm of tutorials, overly specific
examples, and flowery exposition. Granted, it's kind of understandable; that
kind of material is certainly much more fun to write. However, it can often
cause us to lose sight of what is *needed*.

And just to round out the discussion, I'd like to point out that while video
instruction is useful and certainly has its place, it's no replacement for a
comprehensive reference that is easy to search, translate, modify, and
maintain. All of those things are difficult to do with video and won't be
easier any time soon.

Take care.

  Jason