Documentation & Books

[Marian Petrides]

Richard Gaskin wrote:

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

While I agree that life in general (and programming in particular) is a 
process of learning through the application of the scientific method 
(try something, adjust a variable, try it again), the fact remains that 
different people have different learning styles. I didn't see anyone 
here talking about learning programming by reading _alone_, just that 
some folks do better if they have something to read before trying a 
task (or after the first or second abortive attempt).

 >>> You don't learn to draw by reading about it. :)

No doubt. Motor skills, in particular, are very difficult to convert to 
text.  But programming is not a motor skill, it is a process of 
reasoning.

 >>>>>>> It's an inherently intimate/internalized process

But not one that is as difficult to verbalize as is a motor skill.

One could argue that photography and movie making are also largely 
inherently "intimate/internalized process[es],"  but there is a 
plethora of books out there designed to help people who were not born 
with the gift, develop what skills they do have.  And, if you look at 
any bookstore, you'll also note that some of these books appeal to 
visual learners, while others are mainly text, and others are available 
on video for the auditory and visual learners among us.

Judy wrote:
 >>>>Every single one of them has an index.  A well-thumbed one. ... An 
index gives you a visual lay of the land in terms of the language.

I couldn't agree more.  And it isn't all that hard to index a 
volume--there are people out there who do indexing for book 
publishers--I know because I had to proof the index they did for my 
textbook. So, even if time is an issue, an index CAN be provided 
without necessarily tying up the author's own time.

Chipp said:
 >>>>>I take it you're pointing out Dan's book hasn't an index? (PDF 
that is). I think the printed version does. In any case, there is a 
great Search tool for the online documentation inside RR.

What is REALLY frustrating (if it is true) is to find that there IS an 
index to Dan's first book, but that it has not been made available to 
those who purchased only the PDF version.

Just because SOME people find it functional to use the online search 
function as an index, many others do not.  And if Dan (or someone else) 
has already gone through the trouble of indexing the work, then why 
would the index NOT be made available to all purchasers, not just those 
who bought the hard copy?  It costs _absolutely_ nothing to provide it, 
so why not do so????

Chipp also said
 >>>>I agree, it would be really nice if we had more books. But it's 
definitely a Catch-22 type of thing. More users = more books = more 
users:-) Obviously, you're in a tough space, trying to teach students 
Transcript without a good beginner text book.

And, that's the crux of the matter, isn't it.  What's needed is not a 
tutorial but a textbook, not a reference manual but a textbook. What is 
out there right now may be of high quality (and it is, particularly the 
language reference), but it does not meet all the needs of beginning to 
intermediate users.

I reiterate my original point:  index and screenshots with a 
description of every dialog, menu, etc. that the user sees.

And, one more suggestion:  to accommodate the real newbie programmers, 
move the most introductory material (the stuff in Revolution for New 
Developers) to very front of the User's Guide.  Experienced people can 
always jump over it, but newbies may never make it to page 55 and, 
thus, may never find it.

An aside:  at one time, HyperStudio (a HyperCard-like program for the 
Apple II) had quite a following among secondary school educators 
developing teaching aids for their classrooms.  Maybe the whole 
hobbyist thing has passed us by, but I can't help thinking that a 
little emphasis on the ease with which one can do SIMPLE tasks with Rev 
might broaden Rev's market considerably--which would be to all of our 
advantages.

My 2 cents.

M