The Documentation

[Timothy Miller]

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