At 8:20 AM -0700 8/20/2001, Marian Petrides wrote:
>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.
Thanks. (Although I think it is inaccurate to refer to the documentation as
mere "help screens". There's about a book and a half of text in it, and
it's in-depth, not a series of screenshots with callouts.)
>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.
There is already a table of contents. An index is definitely a crying need
and is On, as they say, The List. ;-)
>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.
The new imageSource property will make it a lot easier for me to include
screenshots, although I'm not sure whether this will make it into the 1.1
version - there are issues about size reduction and platform specificity I
need to resolve (basically I'm probably going to end up using Rev, Virtual
PC, and AppleScript in combination to get the screenshots I need).
>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.
Have you looked at the Menu Reference?
>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 ...
Maybe so, but wouldn't a newbie naturally look under "For New Developers"
on the very first documentation screen he or she sees? (Maybe not - I am
toying with the idea of showing the "For New Developers" page of the
documentation the first time the docs open, instead of making users click
that entry.)
>I hope you take this in the way it was intended--as constructive
>commentary not destructive.
Oh, definitely. I agree with much of the criticisms, and even where I
disagree it gives food for thought about how to make what's there more
accessible and easier to find. Most technical writers would kill for this
level of thoughtful feedback from their user base.
Thanks for your thoughts!
--
Jeanne A. E. DeVoto ~ [EMAIL PROTECTED]
http://www.runrev.com/
Runtime Revolution Limited - Power to the Developer!
