[boost] About the tutorial / Re: GIL - Breeze presentation posted

From: rasmus ekman (m11048_at_[hidden])
Date: 2006-06-29 04:39:17

Lubomir Bourdev wrote:

> FYI - we just posted a 55 minute Flash presentation regarding GIL. You
> may find watching it more convenient than reading the tutorial.
> 

Didn't watch it through, would prefer the toot if only....

The breakdown of the type-naming system ("gray_8c_view_t" etc) was very instructive,
it might be good to have it this clearly in the beginning of the tutorial.

It seems this would imply a (brief!) walk-through of the models,
quite early in the tutorial. This would also be useful.

It is not instructive to have discussion of optimization right in the beginning.
First get the concepts settled, then offer a page on how to do things the best way.
If that's at all important - we know how to write loops, so your main argument
is (should be) that we're already winning if we use your library,
as it's very generic, and practical. (And you may be right.)

Here's where the tutorial is lacking IMO:
A good tutorial gives a (nifty) solution to a problem (like gradient, that's fine),
*and* it links to the higher-level parts of reference docs. (*)
So by re-reading and clicking links we get a tour of the most important
classes or concepts, and coming from a worked-out example we see how they fit together.

The body of the toot has two links in the first 4-5 screenfuls of text+code:
one to the include-all header *source-code* (what are we supposed to do with that??)
and one to interleaved_view, which is... well, something I'm not ready
to understand at that point. A link to the image_view class would be better,
or at least gives something to read.
When you next discuss Locators, there's no link at all.
A link to class pixel_2d_locator might be a good idea at that point,
because it has a description of what locators are.
And so on.

The presentation gives a little more high-level stuff, and suddenly it makes sense.
This allowed me to get to the good parts of your library quickly,
earlier attempts just failed, couldn't see where to begin.
(But then I'm not top of the class, just a potential user...)

Maybe I'm just saying that the descriptions in the classes I mentioned
(and maybe some other I didn't see) should be moved higher
up the documentation hierarchy, to places where new visitors will find them.

Good luck with reviews etc, and thanks for the opportunity to study
(and indeed perhaps make use of) a good generic library!

        re

(*) I made up that definition of "good tutorial" just now, but think it almost makes sense.
(A little bit?)