atom feed10 messages in[Bf-committers] Including documentati...
FromSent OnAttachments
mindronesNov 6, 2011 1:04 pm 
Jason van GumsterNov 7, 2011 6:45 am 
KnappNov 7, 2011 2:10 pm 7, 2011 10:52 pm 
KnappNov 8, 2011 6:17 am 
mindronesNov 8, 2011 6:52 am 
KnappNov 8, 2011 10:32 am 
Kel MNov 8, 2011 10:48 am 
Αντώνης ΡυακιωτάκηςNov 8, 2011 11:51 am 
mindronesNov 8, 2011 12:17 pm 
Subject:[Bf-committers] Including documentation in BCon cycle
From:mindrones (
Date:Nov 6, 2011 1:04:16 pm

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


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