Documentation & Books

[Richard Gaskin]

Judy Perry wrote:

 > ...the majority of my students are 3rd and 4th year CS majors who
 > STILL find the documentation unusable (yes, they're partly lazy;
 > but they're also partly clueless as they've never used anything
 > like this model at all and just don't know where to start)

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


As 3rd and 4th year CS majors they've probably learned most of what they 
know from dissection.  Have they applied that with learning Rev by 
downloading stuff from the User Contributions page?

Yes, the model is unique to xTalk, but if the learner is at all familiar 
with Pascal and English they can read Transcript.  Actually, the Pascal 
is just a minor boost -- if they already have a basic understanding of 
progamming essentials (loops, conditionals, assignments, etc.) then the 
range of things they need to learn are few, at least to get them 
familiar enough to do meaningful dissection of any of the large body of 
published xTalk code out there, and of course to reinforce/expand what 
they learn through experimentation.

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. :)

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


 > An index...would be a huge improvement (online search
 > facilities only help if you know what you are looking for;
 > if you already are familiar with the terminology).

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.


 > 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.

-- 
  Richard Gaskin
  Fourth World Media Corporation
  ___________________________________________________
  Rev tools and more:  http://www.fourthworld.com/rev