[Bf-committers] Including documentation in BCon cycle

[Knapp]

On Tue, Nov 8, 2011 at 3:52 PM, mindrones <mindrones at gmail.com> wrote:
> 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)

That is for sure. One of the reasons I really liked Blender was the
2.4 manual. It was great. I wonder why?

> * 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.

Ya but at the same time lots of us do 30-90 minute vids.

>
>> 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

Yes, but they are all OK on Wikipedia and could be here too with the
right set up.

> * you can't paste a book or a blog page in the wiki without permission

Clearly a push not pull situation. I think authors and bloggers would
be happy to try and keep a link page up to date if they knew it was
there and the users knew it was the  first place to stop when looking
for something. Blender.org should be the first or second place (behind
Google) that users go for their info. As it stands, it is about the
last place I go but it used to be the first.

On the other hand we already have the books. Did you know that? I know
it took me a long time to find them when I knew they were there! These
are some great sources of info! They SHOULD be very easy to find with
Google but they are not.

http://wiki.blender.org/index.php/Doc:2.5/Books
http://wiki.blender.org/index.php/Doc:2.4/Books



> IMHO The wiki should not phagocytize the whole web, but rather be a good
> reference with its own identity and direction.
I think we should keep in mind that we have a manual and it should be
THE source of good info and then we have a wiki. (I know the two
overlap)

> 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.

I have long thought that documentors should be recognized for what
they do just as devs are. I truly can't say a dev is more important
than a doccer in a mature program like blender. The program lives and
dies based on both sides of the work.

> Surely with insights from devs the doc will become much more appealing
> also to professional users and companies :)
>
The biggest problem that I see with blender is the new user coming to
blender and that leaving because they are so over loaded and can't
find good help or docs. God knows we have a great program but without
good intros newbies will leave. I got over this hump because of
graybeards vids on the gui.

I can't wait to do my first ship sailing on the open seas with cycles
rendering of the animation! And think of the blood effects you could
do with dynamic paint! On the other hand what do I use for water?
There are now like 6 ways to do it! LOL. I can just see dynamic paint
particles impacting the top of my sea and spreading out in ripples
with my old time ship reflecting in the water! I would love to know
how you do grass in Cycles! :-)

> Regards,
> Luca




-- 
Douglas E Knapp

Creative Commons Film Group, Helping people make open source movies
with open source software!
http://douglas.bespin.org/CommonsFilmGroup/phpBB3/index.php

Massage in Gelsenkirchen-Buer:
http://douglas.bespin.org/tcm/ztab1.htm
Please link to me and trade links with me!

Open Source Sci-Fi mmoRPG Game project.
http://sf-journey-creations.wikispot.org/Front_Page
http://code.google.com/p/perspectiveproject/