Constant 'Nonsense' about RR documentation

[Richard Gaskin]

David Burgun wrote:
>> I learnt Hypercard without a book,
>> and I extended my knowledge, as RR extended xTalk, in the
>> same way:
>>
>> by doing!
> 
> That's great if you have all the time in the world to "doing" it wrong 
> many times! Especially when the documentaion is just plain wrong!

As with the spelling of "documentation" in that sentence, human error 
can creep into just about anything.

While there's always room to expand on the material that's there, I 
don't recall any recent issue you've raised here in which the 
documentation was "just plain wrong".

Sure, some sections could be expanded to address a wider range of needs, 
and for the love of Koresh I'd love to see a new TOC.

But factually incorrect?  I'm sure there are errors in there, but no 
more so than with any other documentation project of such scope, and 
none that I can recall as related to the issues you've raised here recently.


A general note on learning styles:

When I first started with Rev I was made quite an arse of myself, 
ranting on the MetaCard (as it was called at the time) list about how 
everything that was different from what I already knew was wrong.  It's 
merely my good fortune that the archives of that old listserve are no 
longer available -- I was a real pain, chock full o' opinions about how 
this was crappy and that was nonsense and everything in between was just 
silly.

Fortunately Kevin Miller and Scott Raney are far more patient than I, 
and in each case they took the time to explain the "why" behind the 
issues I was having.

As I came to understand the "why" of the engine, I came to appreciate 
the thought that went into it.  Today my one of my few remaining gripes 
is that "destroyStack" is a needlessly alarming choice to describe a 
very useful and non-destructive property.  Just about everything else in 
the language ranges from "acceptable" to "pretty darn nifty" to me.

I've mentioned the tool to a number of friends over the years, and I've 
observed that most go through a learning curve similar to my own (though 
most are far more good natured about it <g>).  Transcript is a very 
different way of working, and while I feel it offers unique benefits I 
also recognize it takes a bit of time to grok its unusual nature.

In my experience as a user and a trainer, the learning curve often goes 
something like this:

   Day one:    "What the hell is going on?  Why doesn't anything work
                like I expect?  I hate this damn thing."

   Two days:   "Omigawd, the potential is incredible! If only I knew
                how to use it all..."

   Two weeks:  "After reading the language guide and trying some
                things out, I'm able to do truly productive work."

   One month:  "Now I can do productive work efficiently."

   Three months: "With the flexibility of the language and the handy
                tools in Revolution, I'm seeing slightly greater
                productivity than in my formerly-favorite tool I'd
                used for years."

   Six months: "I love this thing."

   One year:   "I love this thing like no other."


Your mileage may vary; contents may settle during shipping.
But I'd be surprised if after a few more weeks with this thing you 
didn't have a moment when you sat back and thought to yourself, "This 
Rev thang is pretty cool."

--
  Richard Gaskin
  Managing Editor, revJournal
  _______________________________________________________
  Rev tips, tutorials and more: http://www.revJournal.com