Documentation & Books

[Judy Perry]

Richard,

I largely agree with your observations:

On Tue, 6 Jul 2004, Richard Gaskin wrote:

> What percentage of your students have completed all of the tutorials
> that ship with the product?

Hard to say, as I don't test them on this.  I do tell them I expect them
to complete all the tutorials.

<snip>
>
> Reading is a poor way to learn programming.  In any programming language
> the most meaningful learning is accomplished through experimentation.
> In 15 years I have met no one who learned programming by reading alone.
>   It's an inherently intimate/internalized process, completely unlike
> learning history or philsophy and more akin to learning math and art.
> You don't learn to draw by reading about it. :)

I agree; but when you get stumped there's nothing like a well-organized
and documented printed reference with an index.

> True in some cases, but since v2.0 not very.  There's a lot of "How do
> I"s and an extensive recipe collection.  Coupled with the tutorials and
> the many user contributions there's a lot there for all but the subset
> of learners who maintain the belief that they can learn programming by
> reading about it.

And, again, I largely agree... BUT...

I happen to have sitting not three feet from where I am now a series of
programming-related books:

The McGraw Hill "Java 2: The Complete Reference"
McGraw Hill's "C++: The Complete Reference"
O'Reilly's "Learning Python"
"Director 8 De-Mystified"
Kamin, DeVoto et al.'s "HyperTalk 2.2: The Book"
Sun Microsystem's "Core Java 2: Advanced Features"
Colouris & Thimbleby's "Hyperprogramming"
Nemeth, Sneder et al.'s "Unix System Administration Handbook"
Visual Quickstart's "JavaScript"
Turner & Land's "Hypercard: A Tool for Learning"
And many others.

And, you know what?  Every single one of them has an index.  A
well-thumbed one. (Not all of them by me, of course).  Real, professional
books (even programming-related ones) have indices.  The lack of an index
gives the appearance of a lack of professionality.  I can't tell you how
many times students have complained about the lack of an index in Rev's
printed documentation (which I ordered and make available for them to use
in-class).  An index gives you a visual lay of the land in terms of the
language.

> Should I draft a "Transcript as a Second Language" article?  I've been
> tempted to do so for some time....

Perhaps. I'd be interested!
>
>
>  > I think Rev's model is sufficiently visual and high-level so as
>  > to not explicitly require basic CS knowledge.  For it to succeed
>  > in K-12, this MUST be the case.
>
> K-12 is a highly specialized audience, for which one would expect a
> completely different set of docs and possibly a different UI if it were
> to be successful in that niche.

It's funny that you mention a different UI. The nine of so novice
programmers (read: zero exposure to programming) who tested my
"Introduction to Rev" stack with a substack on mouse events/messages had
ENORMOUS modality problems which largely arose by not understanding the
interface, and, in particular, the modality between authoring mode with an
arrow and browsing mode with a hand (which, again, calls to mind similar
problems encountered by early MC adopters on the HC list).  Hence my
question later to the list on how to script hiding and later revealing the
Rev UI at the end of the mouse events  module so that they could learn
programming by peeking under the hood and fiddling with things.

Judy