atom feed10 messages in org.blender.bf-committers[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 
f.pa...@gmail.comNov 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 (mind@gmail.com)
Date:Nov 6, 2011 1:04:16 pm
List:org.blender.bf-committers

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