[Bf-committers] Including documentation in BCon cycle

[f.paglia.80 at gmail.com]

I'm not a developer so I see your suggestion from an artist point of view:
It's an incredile pain try to figure out how a tool works!
Really, I think here in our studio we spent dozen of hours in testing, defining our own ideas of what is done by a tool without really know if what we imagine is true.
And this in many situation lands to not use that tool but just find another way to do something that works!

I agree in the relationship:
No docs = not ready for trunk

Maybe it's time to hire someone to get a well documented wiki ;)

E-Mail Sent via BlackBerry from BT Mobile

-----Original Message-----
From: mindrones <mindrones at gmail.com>
Sender: bf-committers-bounces at blender.org
Date: Sun, 06 Nov 2011 22:04:29 
To: bf-blender developers<bf-committers at blender.org>
Reply-To: bf-blender developers <bf-committers at blender.org>
Subject: [Bf-committers] Including documentation in BCon cycle

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
_______________________________________________
Bf-committers mailing list
Bf-committers at blender.org
http://lists.blender.org/mailman/listinfo/bf-committers