[Bf-committers] Including documentation in BCon cycle

[mindrones]

Hi all,

Bastien and I are in the middle of reviewing the 2.5 manual and, sadly,
it's not in a good shape, really. A complete report will follow in
docboard mailing list.

We'll work to grow the wiki team but really, I think it's time to
rethink a bit about the documentation, especially adopting a 2 months
BCon cycle.

I'd like to propose a very simple way to get stuff documented.

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

We have discussed this in irc a bit and many (would) agree, and it was a
hot topic at the Blender Conference too as far as I know.

Really, having faster release cycles is all good, but it has to take in
account documentation too, otherwise users will get pissed off after 5
releases in a year and no decent docs.

And even if users are happy like this (which I doubt), I think it's a
waste having such beautiful tools undocumented: I'm sure a great part of
the developer work won't be used at all, which is a shame :)

IMHO the documentation has to start from the developer, not from users.

--

A couple of proposals to make the developers life easier on wiki docs.


1) Informal chats
---------------------------------------------------------------------------

The dev explains the tool he has developed in an informal chat with the
documenter, which puts the info he gets in wiki nicely.


2) Unformatted docs from devs
---------------------------------------------------------------------------

Since many suffer the mediawiki syntax, it would be ok even if the
developer types pure text in a wiki page, not formatted as wikitext.

Writers would then help formatting, beautifying, adding tutorials,
images, examples, etc.

--


Any feedback is welcome :)


Regards,
Luca

____________________________

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