[Bf-committers] Including documentation in BCon cycle

[Knapp]

 ----------------------------------------------------------------
>> ¦                                                                ¦
>> ¦  Documentation phase should be included in the release cycle.  ¦
>> ¦                                                                ¦
>>  ----------------------------------------------------------------
>>
>> Ref: http://wiki.blender.org/index.php/Dev:Doc/Process/Release_Cycle
>>
>>
>> In other words I'm saying:
>>
>>  -------------------------------------------
>> ¦                                           ¦
>> ¦  No documentation in wiki -> No release.  ¦
>> ¦                                           ¦
>>  -------------------------------------------

I love the idea but it needs a lot of limits. First, I want to see
things released as soon as they are done. I don't want to see dev
productivity negatively impacted by them being forced to wait because
they did not write a book about their code.

I do tutorials and I often do them on very little solid info. I get
that info by asking on IRC or reading release notes, emails here, or
the devs blogs. So, not releasing until the docs are there is a lot
like not releasing until the the code is bug free. A good judgement
call is needed about what is enough doc before the code is OKed for
release.

I think the rule should be that the code should have at least minimal
documentation. IE I just made a new thing called grease pen. You turn
it on with xxx and you have features x,y,z and it is intended to help
collaboration between artist by drawing on the work screen.

Something this simple is a great help in jump starting the advanced
users to learn and then write more docs. A contact email is of great
help so we can ask about details that we do not understand. Naturally
the dev writing great docs or making a video is better but devs should
use their time to write code and not extensive newbie directed docs.

Currently a bigger problem is finding the docs and films that are
relevant to the newest version and not something that is 10 years old.
The last big update to the manual greatly helped but their is still a
problem on the WWW and Google searches.

Tracking the state of documentation for each part might be of great
help. Perhaps some sort of rating from 0= no docs to 10 great
professionally written docs. Then writers could search out functions
or features that need documentation more easily. I often wonder what
tut film I should do next, something like this would help me know what
really needed the most work.

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