[Bf-committers] Including documentation in BCon cycle

[Jason van Gumster]

I very much agree with the thrust of Luca's email. Though, I'd suggest this:
rather than postpone a full release to wait for documentation, treat a lack of
documentation in a new feature as a bug. If that bug is not squashed, the
feature cannot be included in trunk for the current release cycle.

  -Jason

mindrones <mindrones at gmail.com> wrote:

> 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