Phil Davis wrote:
I think some things can be more effectively (or maybe just more quickly) "gotten" by reading than by other means:
- the models and metaphors upon which a language draws for its order and vocabulary. These things tell you what you can expect to find as you explore the language.
Agreed.
And I fully agree with Judy's observations about the value of a good index.
A comprehensive topical index is labor-intensve to produce (an automated
index only goes so far), but hopefully this is recognized by the folks at RunRev as the #1 top priority for any documentation enhancements in future versions.
- the vocabulary itself. It's hard to gain comprehensive command of a language without approaching it systematically, and that usually means following someone else's proven path.
Agreed here too. With more than twice as much content as Macromedia Director's documentation, spending some time using the search tool and reading the results will pay off handsomely.
So just to clarify, my opinion is somewhere between "the docs are perfect" and "the docs are horrible". I observe that many have faced
difficulties grasping some of the concepts unique to Transcript (indeed
that's my motivation behind writing articles on it), but I also observe
that a few thousand have come to productive proficiency with even the
current and former docs.
I think it comes down to the intended audience. I paid $995 to get a professional development tool, and if you've ever had to deal with OS APIs erroneously documented (if they are documented at all), you come to appreciate what Rev offers. Even the venerable "HyperCard XCMDs" by Gary Bonds is replete with errors.
Multi-platform software development requires some background with a lot of issues far beyond Transcript, like OS X bundles, the Win registry, Finder info, ASCII, and the basics of memory management, file I/O, and a host of other things. That Rev's docs addresses any of these at all is very generous of them. Once you've learned those things you've already done the hardest part.
If RunRev is interested in markets other than software developers I recognize that my expectations and those of others will differ significantly, and will happily defer to the recommendations of those who have more experience with meeting the expectations of such audiences.
But I feel it may be useful to acknowledge that we're dealing with two very different goals here:
- make RunRev as popular as it can be
- learn what you need to move on with your work
These are not mutually exclusive, but they are different. Of course, for the long term, serving the first goal will make the second go away. But if there's a specific need today, rather than wait for some future version there are ways to get what you need now and move on. And while they're far from perfect, I know of no other general-purpose cross-platform development system that makes it much easier.
My interest in helping people find immediate solutions with the resources at hand is not sycophancy, as one disgruntled poster having a bad day once suggested, but far simpler:
I feel programming in Transcript is a good time, and would like it to be for others as well. I don't work for RunRev so I can't affect what they do, but I can help others to take the engine by the horns and ride it wherever they need to go, just as Kevin, Scott Raney, and others helped me stop griping and get results instead. I can't promise anyone a cushy saddle -- only RunRev can do that -- but I can help them get to their destination with as little bucking as possible.
And frankly, it isn't all that bad. Yes, it can be improved, but take a good look at the docs included with Director or ToolBook or other tools that cost more than twice as much and ya' get a little perspective. :)
Anyone subscribed to this list has already taken the most valuable step most programmers take when learning any new language: diving into the knowledge pool of native speakers. NNTP predates HTTP; there's a reason for that.
So, what was the question that prompted this thread?
Or maybe more useful:
What did you search for with the Help->Search Documentation tool, and what did you find?
-- Richard Gaskin Fourth World Media Corporation ___________________________________________________ Rev tools and more: http://www.fourthworld.com/rev
_______________________________________________ use-revolution mailing list [EMAIL PROTECTED] http://lists.runrev.com/mailman/listinfo/use-revolution
