Thanks for asking for input, Jeanne.
1) First of all, for a product costing $350 there should be SOME printed
documentation OR at least the ability to easily print a PDF document, a Word file
something like that. Online help screens just don't cut it if you have no idea what
you are doing. The only reason I managed to figure out how to use Rev was that I've
use hypercard a lot. I would like nothing better than to recommend Rev to a neophyte
but, unless they have a fair amount of programming background I'm afraid they'd be
totally lost if all they had were the help screens.
I am one of the people who needs to leaf through a hard copy to get the point---what
I had to do was to do screen dumps of all the screens from the tutorials and from the
Encyclopedia and then paste these screen dumps into a Word document. This was a
colossal waist of time--and had I not loved Rev as much as I do I simply would not
have done it. Somewhere buried in something I read I found that I could ? Opt-click
to select text and that would have been a little better than screen dumping but not
much.
2) Second, there really needs to be an index and a table of contents--a way to find
things you know should be there but can't find readily.
3) There really need to be screen shots to show the various menus, palettes, etc. so
you can see that what you THINK the text is talking about is indeed what the author
meant--see the Visual QuickStart and Visual QuickPro guides from PeachPit Press.
4) In conjunction with, there should be a section that covers each and every menu,
and each command on every menu, telling you what it does and when it is used--with
crossreferences to other ways to do the same thing--e.g. do it from a menu (e.g. the
Object Menu) vs do it in the Application Overview (and when you would rather use one
vs the other. For example there are several ways to copy cards but I had to ask for
advice from the mailing list when I tried to do it.
(Note also that even though I HAD printed out the material I mentioned above, I had
forgotten the term "Application Overview" and could not find it readily in the dox I
printed out (no screen shots at all in the help screens) and had to boot my Mac to run
Rev to find the term. This shouldn't be necessary.)
5) There needs to be a getting started chapter (in addition to the tutorial) that
walks the newbie through the concepts of messages, messaging hierarchy, what an object
is, etc. YES, I know this stuff is in the Encyclopedia but _I_ knew where to look for
it. A newbie will just be confused as heck and probably give up on Rev the same way
they gave up on Director/Lingo ... If I recall the entire first half of Danny
Goodmans' book is "getting started" stuff--and that amounts to 2 or 300 pages. I read
the whole thing and really NEEDED that intro to get up and running.
I hope you take this in the way it was intended--as constructive commentary not
destructive. I think that taking time to create good dox for both newbie and advanced
users will make the difference between Rev being a niche product and becoming more
mainstream. Hope these suggestions help.
Marian
-----Original Message-----
From: "Jeanne A. E. DeVoto" <[EMAIL PROTECTED]>
Date: Mon, 20 Aug 2001 03:38:11 -0700
To: [EMAIL PROTECTED]
Subject: Help improve Revolution's documentation
> A few people on the use-revolution list recently have complained about the
> 1.0 version of the documentation. In the attempt to improve the docs, I'd
> like to solicit more information from those who have found the docs
> inadequate.
>
> The complaint I'm hearing is about conceptual documentation - introductory
> material, overviews of functionality, and general concepts, such as the
> information in the Encyclopedia. However, a couple of posts have described
> the documentation as though this material weren't there at all. (One poster
> mentioned the language dictionary, glossary, and "how to" stack as though
> this were all the documentation there were. Another spoke as though the
> first of the six tutorials were all the non-reference information in the
> docs. Another post spoke of having obtained an overview of REALbasic by
> spending an hour skimming the documentation, but didn't mention having been
> able to do the same with the equivalent parts of the Rev documentation.)
>
> So I'm considering whether people:
> - Have specific questions that aren't being answered by the encyclopedia
> - Want the encyclopedia material, but haven't been able to find it
> - Have found it but are not comfortable reading it through, for whatever reason
>
> Obviously, my approach to improving the docs (more orientation info? better
> navigation? format changes?) for these folks will vary depending on exactly
> what problems people are having with this material, and only users of
> Revolution can answer these questions. What's your view?
>
> --
> Jeanne A. E. DeVoto ~ [EMAIL PROTECTED]
> http://www.runrev.com/
> Runtime Revolution Limited - Power to the Developer!
>
>
>
--
_______________________________________________
Get your free email from http://webmail.earthlink.net
