Documentation & Books & related

[Dan Shafer]

Wow. I have now read every single post in this thread and spent a lot 
of time thinking about what is  being said vs. what is being left sort 
of unstated or assumed. While I would never claim my summary/analysis 
here to be authoritative, here's what one user/writer has gleaned from 
the conversation.

1. Revolution as currently constituted does not have a friendly 
out-of-the-box experience for the complete newbie. This is partly due 
to the organization of the docs (which appear to become progressively 
easier to use as you immerse yourself in the environment and its 
terminology) and partly because Revolution, unlike HyperCard, greets 
the newbie with a blank screen that basically dares him or her to 
figure out how to do something  useful.

2. RunRev is a small company and perhaps shouldn't even *try* to be all 
things to all people. Focusing its attention, as it has to now, on 
people with either some programming background or at least a strong 
interest in/inclination toward programming as an art/skill has the 
unfortunate side effect of leaving newcomers feeling unwelcome but it 
may not be feasible to be both a powerful development tool for people 
who have the mindset or skill set or interest to be programmers *and* a 
tool for newbies who "just want to make something useful happen."

3. As Chipp Walters has said a couple of times, nobody said this would 
be easy. But there *is* a sort of implication that it at least won't be 
terribly hard. Rev does not deliver against that implied promise, as 
described in item #1, above. Still, there *is* a course of action, 
outlined by Chipp, that will lead at least many people to become 
productive in Rev.

4. RunRev is working hard on new docs and a new out-of-the-box 
experience for the next release of the product.

5. Meanwhile, there's a clear need for lots of step-by-step examples. 
The issue is what topics need this kind of coverage and are not yet 
covered in Rev docs. I'll start another thread to gather input on that 
topic as soon as I post this.

At the end of it all, one undeniable fact persists. Many hundreds of 
people, mostly probably from *some* programming or scripting 
background, *have* managed to find their way through the docs, this 
list, and the absolutely essential trial-and-error that is part of 
learning any practical skill and have become proficient enough to 
produce satisfying and satisfactory solutions. So while improvement is 
definitely called for, we are equally definitely starting from a very 
high plateau of a beginning.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Dan Shafer, Revolutionary
Author of  "Revolution: Software at the Speed of Thought"
http://www.revolutionpros.com for more info
Available at Runtime Revolution Store (http://www.runrev.com/RevPress)