At 1:16 AM +0300 8/17/01, Douglas Wagner wrote:
>I seem to have ruffled a few feathers yet no one has asked me what I mean
>by adequate documentation.
To be fair, you didn't merely say that Revolution's documentation was inadequate. you
also said that Revolution was "badly documented," stated that there was "no detailed
documentation," and speculated that this might be a purposeful deception on the part
of Runtime Revolution.
Finally, in response, Richard Gaskin did in fact ask what you meant when he said,
"Which programming systems [documentation] would [you] cite as good examples for Rev
to follow?"
>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.
If you haven't already, check out the "Revolution for HyperCard Users" section. To get
to it, click on Help, click on Revolution Encyclopedia, click on any entry, and enter
HyperCard in the search field.
After that, have you looked at the tutorials?
>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.
>
>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.
This again seems like an unfair characterization. What gives you the impression that
Runtime Revolution is giving the documentation short shrift? But I see that I'm
falling into the assumption trap, so I'll simply close by saying that REALbasic's
documentation is certainly a worthwhile target. Hopefully Revolution's docs can be as
good as REALbasic's 3.0 docs by the time Rev 2.0 comes out. :-)
regards,
Geoff
