On Oct 24, 2007, at 12:12 PM, Richmond Mathewson wrote:
If RR is to go from, frankly, a niche RAD... into the killer App
it should
be (or, to be extremely corny, "the killer App
HyperCard once was")... it needs documentation that will allow
people to
follow a cognitive apprenticeship fast and
efficiently.
Precisely.
I love the part about RR becoming the killer App HyperCard once was.
RR enthusiasts sense that potential, and "get" what a killer App
HyperCard really was.
I learnt RR by trial and error, old HC knowledge
(founded on Danny goodman's EXCELLENT book...)
Me too. However, in my case, my understanding and skill have not
grown much beyond that point.
I suppose I might be smart enough, barely, but I'm neither a computer
hobbyist nor computer professional. To me, a computer is a tool not a
toy. Computers provide access to amusement, at times, but are not,
per se, amusing to me. I don't have the time or inclination to become
a Jedi Knight of Transcript. I just want to use it when I need it.
Maximum functionality from minimum investment of time and effort --
that's my desire. Users who fit this description, more or less, were
the original target audience of HC, as far as I know.
It seems there aren't many RR users like me, at present. The majority
of discussion on the use-rev list is over my head, for instance. Most
users seem much more knowledgeable than me. But it seems like there
are millions of mildly geekish potential RR users out there. If they
find the docs approachable and digestible, they might discover RR and
become enthusiastic. Otherwise, it just isn't going to happen.
Jim Ault wrote:
Moving off topic a bit.. the sample stack library, much like Rev User
Spaces. Again, Beginner, Adv, Expert ratings.
Showing a working example is worth a 1000 visits to the
Dictionary. I might
be exaggerating, but not by much.
Sample stacks don't consistently work well for me, especially if they
are sample "projects." Buttons, fields and graphics are easy. Scripts
are hard. The projects themselves rarely interest me.
Sample lines of script in the docs work great for me.
If the docs, in their current form, had five or ten times as many
sample lines of transcript for every command, property, function,
etc., and, sometimes, possibly, very short working scripts, I would
almost always be able to answer my own questions. The large number of
samples would reflect various contexts and purposes, varying degrees
of difficulty, and so on.
If I have too few examples to study, while the definitions and
discussions remain terse, it's just too hard.
A sprawling comprehensive documentation stack, combining explanation
with many working examples, can be imagined. However it might be too
exhausting and expensive to do it well. And it's better not to do it
at all than to do it badly.
One reasonable alternative would be lots and lots of tiny, simple
stacks, each one clearly demonstrating, with working examples, the
use of a single command, property or function. The user could choose
between terse and verbose explanations, simple and complex working
examples, and so on. An individual RR user could put one together in
an hour or less, in many cases. If a wiki isn't quite palatable, it's
possible that contributors could upload their mini-tutorial-stacks to
a single site, where they would be carefully indexed and cross-
referenced, and made available for download. Users could rate each
stack for accuracy, ease of use, or whatever, without opening the
site up to all the chaos and uncertainty of a real wiki. Ideally,
every command, function, property, object, etc., would get addressed
by at least one tutorial stack. A site like this could be maintained
with minimal expense and effort.
I know it's possible that many RR tutorial stacks like this already
exist. I don't have the time or desire to hunt for them. Ideally, I
could find them with a click whenever I consulted the docs.
It seems my fate to embarrass myself on this list, continually, so I
might as well confess. Bjorne's quasi-wiki sounded very promising,
even inspiring. I downloaded it, looked it over, couldn't figure out
how to make good use of it, though I got the general idea, and
couldn't quite understand how it works. How's that for irony?
I do eventually figure these things out, so don't feel sorry for me,
or instruct me. I mean to make two points.
First, the knowledge gap between a highly skilled user and a user
like me is very large. The highly skilled user might find it
impossible to walk in the shoes of users like me, and therefore might
not adequately understand our documentation needs. If highly skilled
users want to attract users like me to RR, they need frequent reality
checks from us.
Second, the elementary portals to the RR experience need to be more
idiot-resistant, somehow. As a moderately skilled HC user, I very
nearly gave up, completely overwhelmed, the first time I double-
clicked on a button in RR. Bjorne, I admire your contribution, but
please improve its idiot resistance.
We must have some subscribers in the greater San Diego area. I'm
wishing you well.
Cheers,
Tim Miller
_______________________________________________
use-revolution mailing list
use-revolution@lists.runrev.com
Please visit this url to subscribe, unsubscribe and manage your subscription
preferences:
http://lists.runrev.com/mailman/listinfo/use-revolution
