The Documentation

Richmond Mathewson geradamas at
Wed Oct 24 15:12:24 EDT 2007

This is an interesting discussion; and mainly, for me,
because it reads as, only, a discussion about how
users of Runtime Revolution are going to access the
proposed documentation.

What has not been addressed are:

1. Any pedagogical questions at all -

2. Heirarchy of difficulty.

3. How one can design a set of documentation which,
while addressing extremely basic concepts (e.g. the
conceptual leap that is needed to understand that
sometimes A+1=A) also will satisfy rather more
sophisticated users.

Considerations such as:

1. Target age group . . . 

2. Type of end users to be targetted ( e.g. educators,
professional computer programmers, pensioners who want
to try programming, and so on, ad nauseam) . . .

I sat my 11 year-old (well, now he's a 12 year-old)
down in front of my Mac mini and DC 2.6.1 and told him
to get on with things and read the documentation: he,
predictably, and understandably, said something
unrepeatedly rude after 15 minutes. I then had to sit
down with him and 'nurse' him through everything - I
don't mind that, I'm a Primary teacher.

My 75 year-old father wouldn't have a clue either;
even though he has an excellent B.Sc in Chemistry from
the days when Universities did not hand out degrees
like sweeties, and he's a Fellow of the Royal Society
for Chemistry. He, memorably, described the RR
documentation (1.1) to me as "unusable" - and he
taught kids for 35 years.

I learnt RR by trial and error, old HC knowledge
(founded on Danny goodman's EXCELLENT book - excellent
that is for people who have already acquired some
computer knowledge) and learning how to understand the
slightly odd short-hand that had been used in the
current RR documentation (RR 1.1).

Somewhere, under all the other piles of nonsense, I
have a slim volume from an old version of something
(err, its referenced in my M.Sc thesis) which talks
about 'Cognitive Apprenticeships' - this term makes a
lot of sense; but only if the apprentice has somebody
standing by as the 'Master Builder' to guide them.
Really good documentation should be an effective
substitute for that Master Builder.

Now  my Master's thesis (plug, plug) burbled on at
quite some length (err, quite boringly, come to think
of it - never mind, fooled the examining committee -
Ooops) about how 20 odd years ago there had been a lot
of hype about computers and how experts in
non-computer subjects would be able to just sit down
in front of a computer and press a few buttons and
"abracadabra" a super, whizz-bang 'thingy' for content
delivery and/or data processing would just
automagically drop out of the sky . . .

This has turned out to be a "load of fairies at the
bottom of the garden"; for reasons I have gone into in
that M.Sc thesis - it could happen; but it probably
won't [OK, all you companies with tons of ready money
ring me now for me to work on a practically endless,
open-ended project that will break all the rules of

Now, not many people are interested in fairies at the
bottom of the garden. But a hell of a lot of people
are interested in what computers can do, but feel

If RR is to go from, frankly, a niche RAD (tactful,
very tactful, Richmond) into the killer App it should
be (or, to be extremely corny, "the killer App
HyperCard once was" - Steve  Jobs needs a smack on the
hand) it needs documentation that will allow people to
follow a cognitive apprenticeship fast and

And that was written after a day's teaching 5-12 year
olds (12 contact hours) - be glad; it would have been
longer, and more pompous, had I not taught those kids
- and what is even more worrying is that I mean
everything I say :)

sincerely, Richmond Mathewson


A Thorn in the flesh is better than a failed Systems Development Life Cycle.

Want ideas for reducing your carbon footprint? Visit Yahoo! For Good

More information about the use-livecode mailing list