[Bf-docboard] Blender books -> official reference
Mike Belanger
mikejamesbelanger at gmail.com
Mon Mar 8 01:01:32 CET 2010
I've read through mindrones' proposal for the wiki. It has great ideas, I
I've made some follow-up ideas here:
http://wiki.watchmike.ca/
Mike Belanger ( Mikahl )
www.watchmike.ca
On 2010-03-07, at 5:08 PM, mindrones wrote:
> 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
>
>
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
More information about the Bf-docboard
mailing list