Documentations Biggest Flaw

[Dave Calkins]

I have been "learning" Rev for about close to 2 years now and have been 
programing since the days of the Card punch machines, (you didn't want 
to drop your program which could easily have a "stack" of punched cards 
several inches high - debugging a this kind of problem was never a 
pretty picture). I also have a background in education.

Over the past couple of years I have seen many people complain about 
the documentation that comes with RR. I just realized what I believe is 
RR documentation's biggest flaw. It is not the amount of information 
presented. Nor is it the type of information that is presented. It is 
how the information is presented. The information is presented in a 
style that is aimed predominately at one type of learning style. It is 
aimed mainly at those who learn best with a what is called a verbal 
learning style.

There are three different ways or styles in which people learn: verbal, 
visual, and kinesthetic. Educators know that in order to have most of 
their students grasp the information they are trying to get across, 
they must structure and present their lesson in ways that will trigger 
all three types of learning.

Verbal learners will love the rev documentation. They learn best by 
verbal communication. They pick things up by reading or listening. The 
documentation for this type of learner is fabulous.

Kinesthetic learners understand things by taking them apart, putting 
them back together, practicing with the parts. Getting in there and 
swinging the hammer, pounding a few nails, hands on kind of thing; that 
is how they learn best. With rev, they will learn the most as they play 
with the cook book, open up the scripts, seeing how they work, 
modifying them to see what happens. The rev documentation is OK here, 
not great, but it has been improving in this area.

The visual learner needs pictures to "see" how things operate. They 
learn best by looking at screen shots of what is being talked about, 
looking at a picture of the icon being discussed, by watching the 
computer move the mouse on the screen to select the proper menu item, 
by having a little man pop onto the screen and show him what to do, 
etc. This type of presentation is essential to a visual learner and is 
almost non existent in the rev documentation.

I believe that the lack of the visual aspect of leaning is at the root 
of most of the complaints about the documentation. The information is 
there, but many people can seem to find it (they don't know what word 
to type in the find field etc.), nor will they be able to easily grasp 
the information once they do find it. They can not "see" it happen or 
easily follow the instructions on how to learn to use and implement the 
software because a "visual" presentation of the information is missing. 
Even the tutorials are this way. They verbally tell you what you need 
to do, but offer no visual representation of the process or of what it 
should look like. To these people learning RR will be a rather hard 
task. Most  people of this learning style will not push through to 
learn it.

People are usually not just one type of learner, all visual, all 
verbal, or all kinesthetic, but are most often a mix of learning types 
with a predominate preference. I myself am a visual / kinesthetic type 
of learner. People in our world today are usually much more visual in 
orientation, ie. they prefer TV to reading, etc. As such, it is the 
visual learner who will have the most difficult time with learning RR 
from the documentation. When you look at the documentation, it is 99.9 
% text. This is one of the reasons I believe RR hasn't exploded as "The 
Programing Language" for all platforms. It can appear daunting, vast, 
and complex. It is also why many people don't take to it like a duck to 
water.

Don't get me wrong, I think that the amount of information in the docs 
is superb. I also know that adding the visual aspect to the documents 
will add to their size, but it will open up RR to a vastly larger 
audience. It will also, I believe, inspire many more people as to what 
can be done with RR.

Revolution has the tools to have a great learning environment for the 
"Visual" and "Kinesthetic" learner.

Dave Calkins