[Bf-committers] Including documentation in BCon cycle

[mindrones]

Hi,

On 11/08/2011 03:18 PM, Knapp wrote:

>> Maybe it's time to hire someone to get a well documented wiki ;)
> 
> Funny, I was thinking the same thing as I fell asleep last night. One
> person in charge of finding the problems and talking with the devs,
> coordinating of the writers and pulling together all the docs,

what you are saying above is OK for the wiki.

As it's being discussed in docboard and #blenderwiki:
* we're now reviewing the 2.5 manual (not in good shape at all)
* we'll install a reviewing system
* we'll define a team of reviewers with the rights to accept edits made
in wiki, so that the content users will see is always ok
* for each blender module (modeling, rigging, etc), we intend to find a
'main' (not exclusive) reviewer that will take care of:
  * review and and format contents inserted by devs
  * review content inserted by occasional editors
  * hunt for new editors (experienced in blender possibly)
* these modules reviewers will have to communicate with the main admins
(more on this later) to make sure the manual structure/templates/etc are
agreed upon.

This should be a team work.

Though, IMO the first input should come by the developer, which should
write even just a draft (no wiki formatting) the tool documentation.

Otherwise you get the current problems, also outlined by Francesco.

The potential writer has to discover the tool by trial and error, then
find the strength to formalize what he has discovered, format it in good
wikitext, using blenderwiki templates.
Honestly, that's a lot to ask.


> links,
> blogs, vids, books and manuals into a cohesive, updated whole would be
> a god send!

I think this is not a good idea.

Two examples:
* deadlinks are a nigthmare to maintain
* you can't paste a book or a blog page in the wiki without permission

IMHO The wiki should not phagocytize the whole web, but rather be a good
reference with its own identity and direction. We should not trash
everything in, but rather make a good team work, and refine
communication channels: devs -> wiki admins -> writers team -> users,
also formalizing this in the BCon, so that documentation is not an
boring optional, but part of the job of the developer.

Surely with insights from devs the doc will become much more appealing
also to professional users and companies :)



Regards,
Luca

_____________________________

http://wiki.blender.org/index.php/User:Mindrones
http://www.mindrones.com