利用者:Mindrones/Wiki/Proposals/2010

My ideal Blender2.6 documentation guidelines (abstract)

Here you have quick-glace overview of the contents below.

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.

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.

Rationale

Content types

Contents presentation depends on:

• the TASK that the user must accomplish ....READ MORE
  • Reference
  • Manual
  • Tutorial
  • Tech/Theory part

• the available MEDIA ....READ MORE
  • Paper book
  • Magazine/Journal (Ton's idea)
  • E-book
  • Online (text) content
  • Video
  • Audio (Podcasts)

• the desired REVENUES ....READ MORE
  • No revenues
  • Pay for finite block of contents
  • Pay per view
  • Pay per time period
  • Offers

• the TIME since the software release.
  The more the time passes from the release date:
  • the more we have a complete and refined documentation, BUT...
  • ...the more the documentation becomes outdated

Documentation perceived effectiveness

The effectiveness of a piece of documentation depends on:

• the amount of text (usually inversely proportional)
• the presence of images (usually directly proportional)
• the TIME that the user has to learn the content ...READ MORE
• the MOTIVATION to learn, which means
  • you are satisfied with the learning speed
  • you get some result by your self soon
  • you feel grateful for reading: you felt a click with some part of the software that was obscure before reading and now is very clear. In other words you don't feel you're wasting your time.

We would be wrong in thinking that user motivation to learn doesn't depends on us.

I often hear people saying "well it's documentation, people expect big chucks of text to read anyway".

I disagree. It is like saying that an ice-cream is good just because it is an ice-cream, not matter how it's done!

The impression that you are getting nowhere or that the documentation is overwelming can induce people to step back, at least for periods.

And this is a waste of time and a risk for everyone, documentors and coders.

• the user EXPERIENCE in the area involved by the content
  • Is it possible to measure experience? Maybe...
  • Practically, we can test if the user has understood what he just read.

The presence of some automatic method of self-evaluation would be envaluable for the user motivation.
I've thought a lot about QUIZES, for example try this
It would be well possible to add user-editable quizes at the and of each page, in order to:

• induce the reader to read again what he seems to have missed
• "measure" that user (if he logged in) and try to give him contents based on what he has apparently understood reading the wiki (not his real skills)

How to avoid duplicated contents

In the wiki we already have a lot of duplicated contents:

• Manual
• Essential Blender
• Blender Summer of Documentation (BSoD)

They're all very valuable, but now we ended up with duplicated contents in wiki, which means

• multiple efforts writing
• multiple efforts maintaining
• also, multiple efforts reading (distinguishing what you've already read somewhere else in the wiki, which is fatiguing and time consuming)

During the wiki cleanup I have integrated BSoD inside Doc:Tutorials, and people were grateful for that: this confirmed that people prefers to have one and well written resource,rather than multiple ones.

My opinion is that we should avoid to write an "Essential Blender 2.6" separately from the wiki Manual, especially if it is designed to be copy pasted in the a separate section of the wiki after the book will be published. It is unuseful and increase maintenance efforts for no real benefits.

What we need is to design Doc:Manual as a book (I'll elaborate on this in a while).

First, a good WIKI Reference

Current situation

Since currently Doc:Reference is far incomplete, very often people filled the gap and wrote reference pages but right into the Manual. In some case people wrote tutorials instead of good manual pages. Hence currently Doc:Manual is a mix of reference pages, manual pages and tutorial pages.

IMO this trend should stop, and the only way to do it is to provide authors a very solid Reference in the Wiki, well before they actually start to write pages.

Reusing the reference

Reference should be the basic brick for all documentation pages of the wiki. I think it is a mistake to wait for books to be finished to have some decent Reference that wiki authors can use to write about 2.5/2.6.

In mediawiki we can reuse a lot using the powerful feature of transclusion, let's use it!

What is this "transclusion"? I have a page called Doc:Reference/Foo with some basic and useful reference content in it If I need to put the contents of that page in a page called Doc:Manual/Bar In the wiki text of Doc:Manual/Bar at some point I just put {{Doc:Reference/Foo}} This will place the whole content of Doc:Reference/Foo where I have put {{Doc:Reference/Foo}} Whenever someone will update Doc:Reference/Foo that change will be reflected also in inside Doc:Manual/Bar See this mediawiki page

See for example:

• how this page is done in wikitext here
• Mike's followup at http://wiki.watchmike.ca/doku.php?id=start

People is already workin on 2.5!

People have already started documenting 2.5! If we leave things as they are now, in order to transclude material from Doc:Reference in Manual pages, we will have to do a full rewrite of the work that people is doing now, which is a bit stupid, because people will feel their job has been unuseful, and we'll probably lose some or many of them.

Instead, we should give them the tools to use their energy at best.

Design of Doc:Reference

Provided that the Reference will be written with a good design in mind:

• authors will be able to use of it all over the wiki and especially in Doc:Manual
• maintenance will be a lot easier
• the Reference itself could be sold in form of a book

So, if some paid work is really possibile, I would suggest to put money into the design of the Reference so that it can be used in the Manual efficiently. Also, I would use some of the funding of such a project for a good automatic Reference generation (as I'll propose later), so that it will be very easy to have it ready in a printable state yearly.

Let's design the Manual as a book

I would design the Manual as a book, heavily based on the Reference, and I would publish THAT.

This would have the benefit to be constantly maintained by tents of people and it would be easy to publish it yearly. If the reference will be automatic, this is even more true.

Navigation and Crosslinking

Navigation bars of every page should permit to cross link to:

• related Tutorials,
• related Reference pages
• related Python API pages and/or useful Python scripts
• related Release Notes
• related devlopment pages
• ... else?

Currently this kind of cross linking is only done among Doc:Manual, Doc:Tutorials and Doc:Theory index pages.

In a paper book we could add a panel at the end of each section (wiki page) with cool scripts links and/or some API examples related to the section.

Let's create a series of .blend too!

Also, my suggestion is to provide, at the end of each page, some good tools to put the hands on the contents that have been explained, like:

• a series of quizes or self-evaluation tools
• a mini tutorial/example with some useful cases (cross linked from Doc:Tutorials)
• a blend file to work on, linked from an appropriate svn where only authorized people have access

At the moment I have created https://svn.blender.org/svnroot/blend-doc for this purpose: if this idea is ok we can use it (note that it's not ready for the public yet). When the Manual gets published, it could be possible to dump the svn tree into a DVD to be sold together with the Book. This is something the Reference wouldn't have.

If we can build this kind of content, it would be easier to sell books divided in areas (animation, modeling, etc) because each of them would be kinda complete.

Wiki reference the 2.5 way, semi-automatic

Note My terminology about the code might be inexact but I'm quite abstract at this stage, please try to understand the ideas.

At the Blender Conference 2009 I've discussed a lot with Campbell about two interesting documentation features:

• Automatic documentation
• Automatic screenshots ("autodocs")
• User documentation enhancement from the Blender's UI

Autodocs

Automatic documentation

After the conference, Cambpell added a method in the Panel class that let us print values of Blender's UI items at runtime, and I'm using this to extract useful informations to build the Reference. Of course the UI depends on the context, but this should be solved preparing a .blend file and iteratively inspect items in different contexts.

Automatic screenshots

The idea is that since the UI is based on OpenGL we could ask OpenGL (read: Blender) to generate a panel, and then save its pixels in an image instead of putting them on the screen. Thus, with the same mechanism described above (using a proper .blend file for UI inspection), we should be able to "portrait" the Panels in all the possible situations.

Highlighting buttons in screenshots

One thing I often think about is: if we can really generate panels docs via python, and if we really know buttons position in the UI, then we know the buttons position in the generated panel image.

Please look at this extensions: http://commons.wikimedia.org/wiki/Help:Gadget-ImageAnnotator

Move the mouse over this image for example: http://commons.wikimedia.org/wiki/File:Spelterini_Bl%C3%BCemlisalp.jpg

The yellow annotations are very much the same as the ones you have to do *manually* to indicate a button in a screenshot right? See here: http://wiki.blender.org/index.php/Meta:Guides/Style_Guide/Images#Highlights

If we setup that extension, during the autodoc process we could also setup annotations, so that wiki readers can move the mouse over the screenshots to read the buttons documentation.

This would help refining contents a lot since these annotations are editable.

Basic plan

My rough plan would be:

• Prepare a comprehensive blend file with:
  • multiples scenes
  • multiples render layers
  • all type of objects and datatypes
  • etc..
• Solve the problem of finding all relevant information out of blender, preparing a script that for each panel prints all possible options, including:
  • type of button
  • values: default, maximum, minimum (soft and hard limits)
  • position of the button in the panel
  • dependency on the context of button values, position, etc
  • Shortcuts (this demands an important consideration on templates, see below).
  • etc, etc
• Solve the problem (together with Campbell) of how automatically screenshot the UI, saving images in files:
  • we should have a panel image for each situation, depending on selected objects, obdata and so on
  • images should have appropriate names, not necessarily human readable if needed
• If an element hasn't changed after the last introspection, we don't want to generate its image and its wiki content again, because it would increase upload time to wiki for no benefit, so we should think of a db or a just simply a pickle file to store these infos.

If we plan to let users to generate this kind of doc by them self, as it is currently possible for the Py API, we could consider a sqlite db (see how firefox or scons save data).

• Run the script in the prepared blend file:
  • get all the data we need
  • format it for wiki
  • upload it to wiki with a mediawiki bot

New wiki templates

The whole point of automatically retrieve these informations is that:

• at release time in a matter of minutes we get all info we need from blender itself
• wiki authors don't have to do tons of screenshots
• screenshots themselves have a uniform style

General Templates

In order to organize all the informations we would get, we need to format the contents within proper templates. Thus, I'd like to put up some new templates and renew a bit the skin too.

Shortcuts Templates

Another important thing I'd like to do is to encapsulate shortcuts inside proper templates in order to ease the wiki maintainance while Blender evolves, and maybe we can do some cool stuff too, see below (*).

Here's the idea.

Instead of putting in wikitext

"to extrude, press {{shortcut|E}}"

we should really type

"to extrude press {{shortcut|2.5|3dview|editmode|extrude}}"

and put the real command (the keystroke "E") inside Template:Shortcut, where we can specify commands depending on blender version, editor, mode, etc. This way, if we change the extrude shortcut, we just change it in one place instead of changing many pages in the whole wiki.

For these reasons, we need to prepare templates BEFORE we do autodoc.

In general, preparing good templates before such a big documentation job seems obvious to me, even if we don't do the autodoc stuff.

(*) A cool thing we could do is also to let the user to specify in his own Userpage some preferences, for example the Theme or the Keymap he is currently using, and make so that the wiki shows him exactly the shortcuts he is using in his own (customized) Blender, instead of the default ones.

Skin

Also, I would really like to update the wiki skin to get:

• easier contents fruition
• easier/quicker navigation
• better crosslinking

As an example of crosslinking, think about having each single page linked to:

• relevant tutorial page(s),
• relevant scripts page(s),
• relative Python API page(s),
• relative page in older blender versions ("see this in 2.4"),
• same page in othe languages (we do this but there are better ways),
• and so on...

See also these mails to docboard (here and here)

Users suggesting docs from blender's interface

As a result of another another discussion with Campbell at the Blender conference, now we have this cool feature: right-clicking on buttons, in the popup menu we have an option called "Submit Description".

Inserting a description you actually suggest to change the current button description, and your contents are stored here:

http://www.mindrones.com/blender/svn/ (temporary url)

People can review suggestions from that blog and using xmlrpc we can retrieve the good suggestions and generate a patch to substitute approved description.

Currently this is useful to get help from the users to improve the Python API, but...

But, according to Campbell if this proves to be useful we could do the same in many other places other than panels. For example, we could right-click (or similar) on the camera in the 3d view and send useful tips about it (here I'm interested by the possibilities I'm not into discussing development stuff)

If we had multiple lines in the description field, it would be easy for users to suggest small snippets and mini-tutorials about everything many little aspects of Blender. We can inspect those ideas and integrate them in the wiki.

With the same mechanism we can retrieve:

• bug reports
• feature requests

Editing the automatic reference and injecting it back in Blender's code

After we will have the automatic documentation online, very probably it will be incomplete and bugged because while coding a feature some operator might not have a very descriptive text. Here is when the wiki authors can fix things and integrate suggestion from blender users (see above).

At release time, or periodically, a group of wiki authors can review the changes and approve official changes to be put in the new official Reference.

Now those contents should go back into Blender!

The process would be:

Blender -> Autodoc -> Wiki -> Editing -> Review -> Blender

This would close the circle between developers, documentors and users.

For example, look at the proposed mediawiki Annotations extension: they really looks like tooltips in Blender! You put the mouse on the image, and you get an information, it is the same. So in my vision, people editing an annotation in the wiki could end up editing a Blender tooltip without even being aware! :)

This has the benefit that the reference will be embedded in the Blender source code itself, and could be generated locally in any moment, as we are doing with the Python API. Or, it could be generated in other formats then wikitext if we wanted.

See also

• Mike's followup at http://wiki.watchmike.ca/doku.php?id=start
• Meta:Guides/Blender_Wiki_Structure