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 e! ven 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. ;) >From time to time we all overlook the obvious and lord knows how many times I've done so myself, as I did just last week with the diskspace function. There is no shame in that, it's just part of being human; we just get the answer and move on, and it probably helps other readers along the way. No big deal. But to extrapolate that overlooking something obvious always means that there's something critically wrong with the UI or its documentation is not likely to hold up in some cases, and in such cases slows the learning process for others unnecessarily. We're not talking about cooking, which my failed attempts suggest is hard enough to learn (for at least this bachelor). Developing software is an inherently complex task, and while Rev is arguably among the easiest ways to accomplish as much as it lets you do, there's only so much it can do to simplify the process. A 1000+ token interpreter like Rev's is a complex system, integrating with even more complex systems like QT, database engines, and 12 different operating systems. While imperfect, Rev makes the software process orders of magnitude more efficient and easier than traditional methods like C++ or even Pascal (in some cases yielding superior results), and is far simpler to learn than the world's most popular scripting language, JavaScript. And at version 2.0 it's still quite young, with many areas in which it can learn and grow to make that process ever simpler. There are areas where Rev could better exploit the principle of progressive disclosure (a long rant about the evils of Photoshop's UI on the evolution of software design is growing increasingly hard to resist), but as a whole it's not bad and specific suggestions for improvement seem to be heard. << _______________________________________________ use-revolution mailing list [EMAIL PROTECTED] http://lists.runrev.com/mailman/listinfo/use-revolution
