Suggestions for a new Revolution User Guide

[Stgoldberg at aol.com]

As a new Revolution user (former HyperCard/mTropolis user) and having read 
through the User Manual and Dan Shafer's book, I find the program very powerful 
and useful.   However, I'd like to make the following suggestions toward 
producing a new User Guide, and which I think would better attract new users.   
There are important basic features in the present user interface that   seem to 
be inadequately documented even for those with a programming background, let 
alone those totally new to programming.   I suspect Revolution may turn off new 
potiential users unless certain changes are made to the documentation.   My 
suggestions toward a new manual are as follows:
1.   Eliminate   the printed Transcript Language reference guide.   It is 
duplicated in a much more efficient manner in the onscreen Reference 
Documentation window.
2.   Eliminate the "How To" section in the printed User Guide.   Much of this 
is already in the Topics section of onscreen Reference Documentation which 
can be beefed up to include all of the "How To" topics.
3.   Instead, have a single, smaller user manual organized so there is:
     A.   A new friendly introductory chapter describing the general features 
of Revolution.   As is, the manual is not very user-friendly to newbees.   
One has to go through some 55 pages before getting to a section called "About 
Revolution for new developers".   These first 55 pages could largely be placed 
in an Appendix, so that someone totally new to programming does not have to 
wade through it.
     B.   There needs to be a systematic explanation of the various windows 
in Revolution, in particular the Inspector and message box windows, which are 
not presently well documented.   The reader should be taken through each 
checkbox and menu item in the inspector and message box windows.   The Tools window 
also does not seem well-documented in any one place (Where is there an 
explanation as to how to make proper use of the   slider, progress bar, little arrows 
and scrollbar items, and the drawing tools?)   One can find scattered 
information but it does not seem well-organized in any one place.
     C.   There should be a systematic explanation of the main top menubar, 
including all the features of the "Standalone Application Settings" part of the 
File menu, which presently is not well documented.   Thus the "Menus" section 
of the present User Manual should be upgraded.
     D.   There should be a brief overall chapter on Revolution scripting.   
It need not be extremely detailed.   Details can be obtained in the already 
excellent Dictionary in the "Reference Documentation" Window. Also, when Dan 
Shafer completes his book (I still remember reading through and using his 
excellent book on HyperCard scripting some years ago) it should be very valuable in 
pointing out and elaborating on the more advanced and useful things that 
scripting can do.
     E.   I'd keep the Shortcuts and Troubleshooting parts of the present 
User Manual.   The Glossary terms don't have to be listed over 12 pages in the 
Index.   It is sufficient to have them just listed in the Glossary, which could 
actually be eliminated in favor of simply putting a Glossary on disc as part 
of the "Reference Documentation".   In general it is easier to read short 
segments of text on a computer than long paragraphs of text, so the short segments 
(Topics, Dictionary, Objects, Glossary) would fit well being placed on-screen, 
while longer explanations would fit better in a book. (By the way, I have 
been writing, editing and publishing medical books and CDs for the past 25 years, 
at www.medmaster.net, and am used to evaluating which forms of communication 
fit better in a book and which on CD).
     With a single, short, well-documented, organized manual it would be 
easier to attract new users.   I'd be happy to help write (or edit) one myself at 
no charge, if the current developers are interested, since I am so impressed 
with the potential for Revolution, but first I'd have to fully understand all 
the features myself.   
     So far, I've found this forum a great avenue for communication.   I'm 
looking forward to the conference at Monterey.

Steve Goldberg
www.medmaster.net
stgoldberg at aol.com