Documentations Biggest Flaw

[Kevin Miller]

On 21/3/04 5:29 pm, Dave Calkins <davecalk at surfbest.net> wrote:

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

Fantastic post.  You have perfectly summed up what is one of our very top
priorities for the next couple of releases of Revolution!  Stay tuned for
big improvements.

Kind regards,

Kevin

Kevin Miller ~ kevin at runrev.com ~ http://www.runrev.com/
Runtime Revolution - User-Centric Development Tools