Douglas Wagner wrote:
> I seem to have ruffled a few feathers yet no one has asked me what I mean
> by adequate documentation.
Not ruffled, just confused. For example, both Jeanne and myself have asked
you for examples of what you consider really good documentation. Are those
posts not getting through?
> Clearly, Revolution is an interesting application which seems to have
> considerable potential. But there in lies a problem, if that's the right
> word. I understand R isn't merely another HyperCard, so a newcomer to the
> software needs a global view which can only be provided by a document
> designed for the purpose. R's internal documentation is designed as an
> online reference, not a comprehensive guide. A dictionary of commands is
> useful if one knows which command one needs. And the glossary is useful if
> one is unfamiliar with elementary computing terms. A list of "how to" tips
> mau be useful once one is operational.
It's almost like we're looking at different products. I'm looking at the
docs in the Rev Starter Kit 1.0. In addition to all of that, there are the
tutorials which introduce the major features and the reasons they're
important, and an introduction to Rev as a whole. Do you have those in your
installation?
> As an example of the sort of documentation I have in mind, have a look at
> the REALBasic "Developers' Guide" (6.0 mB) and the "Language Reference"
> (4.8 mB). (I've not so far looked at the more detailed indexed language
> reference). After an hour or so reading those documents, I have a clear
> idea of what REALBasic is about, where it fits in the range of IDE's
> available and I have some ideas about how I might use it for my project.
I'll take a gander. Thanks for the reference. That file doesn't seem to be
included in the DB package -- do you have a URL?
> It would be useful if RR made available similar documentation. I understand
> the impulse to concentrate on the code. Still, the marketing weasels will
> say, or should say, good documentation helps sell the product and that,
> after all is what matters, if one would prevail.
Absolutely. It seems Jeanne has already outperformed Macromedia and
Asymetrix -- I would imagine she could do similarly well with a comparison
against RB given the chance to see the benefits of their docs' style.
--
Richard Gaskin
Fourth World Media Corporation
Multimedia Design and Development for Mac, Windows, UNIX, and the Web
_____________________________________________________________________
[EMAIL PROTECTED] http://www.FourthWorld.com
Tel: 323-225-3717 ICQ#60248349 Fax: 323-225-0716
