Documentation & Books

[Richard Gaskin]

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