standalone has plainly readable transcript

[revolution at knowledgeworks.plus.com]

I agree with Richard 100%.  I think it is very far-sighted of him to see that the needless railing against the Rev docs can affect other users' perceptions of the quality of the docs and the quality of Rev.  As Richard points out, the number of keyword tokens that have meaning for the engine behind Revolution is quite phenomenal, and the documentation is really quite exhaustive.  

I've been programming for 20 years, and learnt many different languages and environments.  I have not found anything that comes close to Rev, and I wish Runrev and Metacard tremendous success.  Before I decided that Rev was one of the three or four technologies I needed for ANY possible application development, I looked around at many of the competitors.  Frankly, I think that Rev (and Metacard) are peerless in what they do.  Indeed, the vast power of the engine can be hidden by the simplicity and beauty of the language.  As Richard points out, even Javascript is more difficult to use than Rev.  The difference is that languages like Javascript have more readily-available sources of external documentation/information.  That there is not masses of _third party_ documentation available for Rev is not the fault of Runrev.  

We users have to make the best use of what _is_ available.  There are many places on the internet where if you ask for help, and what you are asking is in the manual, you will be told: 'RTFM'.  When I first started to use Rev, before I would post any questions to the list I would search the docs, search the books I had bought on Hypercard and Hypertalk (subsequent to buying my license for Rev), and search the archives for both Rev and Metacard.  Most of the time, I found the answer this way, and if I did not find the answer I would post my question.  I was embarrassed if it turned out that the answer was in one of these places but I had missed it.  I could not see why I should spend my time writing a clear email expressing my problem when I could spend the time searching for the answer, nor why I should expect someone more knowledgeable than myself to spend thetime explaining to me what was already publicly available.  Now that the docs are fully-searchable, I think there is even less reason why I should miss the answer.

I am no Transcript expert, but I found that on returning to Rev after several months of not using it, it took me no more than an hour to prototype an idea for a multi-platform, freely-distributable web server that would serve up encrypted data to users via a browser.  To find out the necessary information I did a Google search of the list, and searched the documentation, and the prototype took me 1 hour to produce.

Some of the perceived problem with the docs may be the frame of mind in which one approaches Rev.  At the beginning I did not fully appreciate the fact that since there is a 20 year history of evolution from Hypertalk to Transcript it is more likely that any perceived lacking in the language/environment is _probably_ a mistake on the part of the user (yes, we users can make mistakes), and anything that seems not to work _probably_ does work (it might take a little digging to get the syntax right or to change the way in which one thinks it _should_ work).  People, 20 years is a very long time in computers....

My perception is that Revolution enables many people who wish to program to begin doing so, when the intracacies or startup requirements/costs of other environments are prohibitive.  Maybe it is because Rev is positioning itself as an 'easy' way into programming that there are users who expect it to be so simple to use that they should not need to look for information. But I'm quite sure that if they tried many of the alternatives that offer _some_ of the benefits of Rev (e.g. iShell, VB, Python, Rebol, Java) they would have given up already because of technical difficulties and/or price.  And if they did opt for one of these other programming environments, I do not think they would find better a better environment than Rev, or better documentation than that provided by Jeanne, or a more helpful support group than this. RTFM is not an injunction one sees often on this list.

I say all this even though I may well _perceive_ there to be _minor_ omissions in the documentation for Rev 2.0x, and maybe I preferred the GUI of Rev 1.1.1 ...... These are minor or personal, and it is a 2.0 release.  Having downloaded several different faulty or inadequate Java IDEs in the past week, I keep on appreciating what Runrev does.  Of course there will be bugs in the IDE, and there may well be inconsistencies in the language, and there will always be features that are missing for some sub-set of Rev users.  But in my opinion it is a peerless tool, and Runrev are doing a great job.

Regards,

Bernard

>>
As a documentation professional, surely you recognize the dynamic that
occurs once the meme of "the docs are inadequate" grows legs: an element of
"learned helplesness" creeps into the community, in which newcomers read
posts slamming the docs and begin to assume they needn't even try looking.

While specific constructive suggestions sent to Jeanne are invaluable in
providing guidance for further expansion, posts making broad negative
generalizations about the docs can be a disservice to the readers here,
misleading them to believe that finding the answers they need may be harder
than is actually the case.

This latest issue of password-protecting stacks is a good case in point. If
something seems obvious enough to get alarmed over, it may be obvious to the
RunRev team as well, and might well have already been addressed.  The same
amount of effort as required to post an alarming note to the list is all
that's required to recognize that in this case such a post isn't necessary:
Step 3 of 3 in the Distribution Builder has a field clearly labeled "Encrypt
with password" in the middle of the card.

And in the last several weeks a lot of posts have been searching for
language features in which what was being sought is the actual keyword they
were looking for; submitting the same term to the Transcript Dictionary as
was submitted to the list would have yielded immediate gratification.
Sometimes the problem is believing things can be as easy as they are. ;)