[Bf-docboard] Blender books -> official reference

[mindrones]

Hello all,

I've prepared a proposal about this documentation project at:

http://wiki.blender.org/index.php/User:Mindrones/Wiki/Proposals/2010

Below I'm pasting the abstract from that page: each point is then explained better
in the wiki page.

Sorry for such a *very* long answer, but this proposal contains quite all the ideas
I had about documentation during the last 16 months while I've been cleaning
and refactoring the wiki. Please also forgive me for mistakes and for the bad
english, after editing it for so long I had the impression I wasn't able to check
the language anymore :)

Ton, as stated below, I think that the magazine really fits with my approach, cool idea :)

My biggest advices are:

* we should really dedicate some paid work to build a very well written, flexible
  and possibly semi-automated Reference as a base for future works whatever media
  the Blender Foundation will choose,
  
* IMO the wiki should not depend from contents like Essential Blender or books
  in general, even if books are an obvious way to get paid for documenting
  (I've explained this below)

 

MY IDEAL BLENDER 2.6 DOCUMENTATION GUIDELINES (ABSTRACT)
-------------------------------------------------------------------------------------

RATIONALE

    CONTENT TYPES
        How can we divide contents to reach out reader needs and avoid to overwhelm him? 
        Some rationale about different types of contents.
        A really important distinction we have to make clear is among Reference,
        Manual, Tutorials, Theory/Tech (too often this is not the case), see here:
        http://wiki.blender.org/index.php/User:Mindrones/Proposals/2010/Contents_By_Task

    DOCUMENTATION PERCEIVED EFFECTIVENESS
        The effectiveness of a piece of documentation depends on.... ? 
        A rationale about how to make sure the doc is really useful for readers 

HOW TO AVOID DUPLICATED CONTENTS
    We should try to avoid to spend efforts on books for the wiki, it doesn't help the wiki. 
    Instead, let's find a new way to get indirectly paid for wiki contents 

FIRST, A GOOD WIKI REFERENCE
    Too often we see Reference contents in the Manual. This is because the current
    Reference is incomplete. 
    Instead, wiki authors should use transclusion to reuse contents of the Reference a lot.
    So let's use money to build a very solid refence first. 
    Also, let's build an automatic Reference, so that it's always uptodate. 

LET'S DESIGN THE MANUAL AS A BOOK
    If we design and maintain the Manual as a book, we can publish it when we want,
    just periodically making a global review, which helps the Manual too. 
    If the Manual is based on an automatic Reference it will be much more easy to
    publish it yearly. 

    CROSS-LINK PAGES TO OTHER SECTIONS (COOL FOR PUBLISHING)
        It is important that we have some navigation template that links Manual
        pages to its relevant Reference, Tutorials, Extensions, Development pages. 
        Now we don't have this. 
        This would make it easy to publish sections of the manual completed with
        every aspect of a certain argument. 
        This also helps the printed book series: it would be much more interesting
        and marketable because one buys a piece of doc that is very complete and
        covers all aspects he may be interested in (includes scripts, API reference,
        tutorials, etc). 
        Especially if we provide .blend files. 

    LET'S CREATE A SERIES OF .BLEND TOO!
        Every page should have its own mini-tutorial and blend files to be linked
        from an ad-hoc svn tree. 
        These files should accompaign the reader through the Manual from default
        blend file to a cool final scene (modelling, animation, rendering, pipeline, etc...) 
        The blend files should be thinked and designed using the data system in Blender. 
        Example: blend file of the chapter 19 links back to files from Chapters 4 and 7. 
        We should then reuse blends to show new features in new rlease of the Manual. 

WIKI REFERENCE THE 2.5 WAY, SEMI-AUTOMATIC
    I propose here a method to get the Reference from Blender's code itself. 
    The Reference built from the code should be then edited by people, re-inserted
    into the code itself and go through a cycle. 
    New features will be automatically detected, and they will need refinement and
    completation by humans of course, but this would be a good way to stay on track
    with Blender's development. 

    AUTOMATIC DOCUMENTATION AND AUTOMATIC SCREENSHOTS
        I'm working on a patch that extracts descriptions from UI items, put them
        in wikitext and upload it to wiki.blender.org ("w.b.o") 

    NEW WIKI TEMPLATES AND W.B.O SKIN
        In order to present all those info in wiki, I need to do some new templates
        and enhance the skin so that contents can be viewed at will by the user, mainly using some javascript functions. 

    USER SUGGESTING DOCS FROM BLENDER'S INTERFACE
        Another patch we're working on with Campbell let users to send us documentation
        and suggestions, and in the future even small tutorials from Blender's UI! 
        The goal is to have a central repository where wiki authors can examine all
        the suggestions and eventually integrate them in the Reference. 
        This way users all over the world can help completing the doc without
        disrupting their workflow. 
        Like this we can also also gather bug reports and feature requests from
        Blender itself, inspect them, catalogue them and send them to http://projects.blender.org 

    EDITING THE AUTOMATIC REFERENCE
        After the autodoc has been generated and published in the wiki for a certain
        release, wiki maintainer can start editing to complete missing documentation,
        also integrating suggestions that users has input in the UI. 

    THE REFERENCE RE-INJECTED IN BLENDER ITSELF!
        Then we can periodically check the diff beetwen the current reference and
        the one stored in the code and commit the change in Blender's code. 
        If we setup this virtuous cycle, we can expose a very good documetation
        in Blender itself. 
        To some extent, this could even lower load on blender.org servers because
        some documentation (tooltips for example) will be already complete and informative.
        Also, if we find some ways to present documentation in the UI, people
        would stay in Blender to get doc, avoiding to disrupt their workflow. 

    POSSIBLE FUTURE CONSEQUENCES OF EXPOSING THE DOC INSIDE BLENDER
        If we expose the documentation inside Blender, then one might think,
        "ok cool, but then we won't sell Blender books anymore!" 
        I think in the future it could be possible to sell the "integrated
        documentation" as a separate plugin, that have to be registered and paid someway. 
        So, a new form of documentation possibly, but IMO it would the still possible
        to do business with it. 

PYTHON API DOCUMENTATION
    It would be very interesting documenting the Python API with autodocs too,
    letting people suggest examples to be inserted in the API code as form of a cookbook. 
    Another idea is, once we have a good cookbook it would be very useful to "link"
    this section with the .blend repository so that one can test small snippets on
    real-life files. 
    It would be very consistent if we give scripts developers a good source of
    real-life blends to show how to their scripts work. 
    Also the paper book can benefit from havinga good cookbook, to be put at the
    end of each Chapter or Section. 

BLENDER'S CODE DOCUMENTATION
    It would also be very useful to start a Blender's code documentation project
    in parallel and communicating with this one, in order to gather informations
    about used algorithms and formulas, to be input in the Doc:Theory section. 
    This would enhance both the wiki and the paper publications as said above. 
    Example: a certain node documentation would also show the exact formula for
    RGB-> YUV conversion or Chroma keying (very useful). 
    Some way we should find a way to tag functions in the code in order to provide
    a link to their documentation in wiki or elsewhere (Sphinx?). 

PUBLISHING METHOD AND CONCLUSIONS
    As stated above, I think that the future form of documentation should be to
    install paid and registered documentation plugins into software. 
    IMO there's really no point into read the doc out of the software itself. 
    It is difficult though to imagine such a thing today, so we still have to sell
    a physical thing (a book, a magazine) to get paid for our documentation work. 
    If I had to choose a paper media, I'd prefer the magazine:

        * it's faster, you have to block a smaller part of the doc each time,
        * it can depend on the Blender's development cycle, so you can publish stable
          parts of Blender
        * users can be interested in that part only so they can choose to pay less
          but more frequently
        * it certainly is a good method to publish material for different levels
          of expertise (could be "beginner edition", "professional edition", "guru edition", ??) 

    I really hope that before we really start thinking anything cool we dedicate
    some paid efforts to build a very strong Reference first.
    

(expanded at http://wiki.blender.org/index.php/User:Mindrones/Wiki/Proposals/2010)
-------------------------------------------------------------------------------------

Regards,
Luca


_____________

http://www.mindrones.com