The Documentation

Wed Oct 24 16:36:18 EDT 2007

Le 24 oct. 07, à 21:12, Richmond Mathewson a écrit :

> 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.

my comments on these two. The first obvious thing is that quite a 
number of persons are dissatisfied with the documentation that 
Revolution provides. Until now, most (if not all) the answers implied a 
user community effort to provide a better doc. Following Richmond's 
message, I would like to change perspective:

revolution's documentation is bad mainly because the syntax of 
Transcript has departed from the natural english approach of Bill 
Atkinson to more a conventional one like function(arg1,arg2) etc... 
Frankly, I appreciate to be able to "lock objects" instead of "set the 
lockWhetever to true".
I recently had a look at the video library, and I find it awfully 
complicated to remember all of these RevBit1Bit2 keywords: in some 
commands, "Video" comes just after "Rev", in others "Video"  comes in 
third or fourth position: this smells ill assimilated externals. The 
rev team should start thinking about updating the language and the 
parser. For instance revVideoGrabDialog could be synomym with "get 
Video Dialog" or "answer Video" like "answer file" etc...
Revolution advertises its language as being "natural english"; they 
should be careful it remains true. This means more reserved words, but 
not many. On the other hand, if one consider that "grab" for instance, 
should be a keyword, it should be usable with as many kinds of objects 
as possible. This is how the language can be merciful (and hence 
"natural"): by allowing several formulations for the same meaning.

On the documentation: by looking at the excellent BvG stacks at 
http://bjoernke.com/runrev/stacks.php , I discovered that the doc was 
some kind of compressed XML; I mean, why this XML stuff? Why not plain 
Revolution stacks? Some fifteen years ago, I bought "FreDOS'stack", by 
Frederic Rinaldi, which was a collection and database (understand: HC 
stack) of externals. Over the years, I added some buttons, some 
maintainance scripts etc... This was possible because the intellectuals 
means required to customize the stack did not exceed basic HC 
programming, and, most important, improving the documentation stack was 
an exercise in the HC programming and, in some cases, learning to use 
the most useful externals in the stack.

To make it short, when I look at the XML files and their output, I 
think all of this can be translated into stack format. This is what the 
Hypercard team did: their docs were HC stacks. The obvious advantage is 
the ability to do custom searches in the way we are supposed to work: 
using revolution objects. When I think of this XML stuff, I have the 
feeling that the people who did the doc did not believe in their own 
product.

>
> 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.
>

You are all right. The language, the objects, the documentation have to 
be as simple as possible. People can improve the doc (and write custom 
scripts) afterwards, PROVIDED they can understand the primary doc (and 
language description) first.

> 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
> SDLs].
>
> 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
> unempowered.
>
> 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
> efficiently.

completely agree with you. Revolution should be the IDE" for the rest 
of us".

>
> 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
>
>

bye
	Francois

> ____________________________________________________________
>
> 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  
> http://uk.promotions.yahoo.com/forgood/environment.html
> _______________________________________________
> use-revolution mailing list
> use-revolution at lists.runrev.com
> Please visit this url to subscribe, unsubscribe and manage your 
> subscription preferences:
> http://lists.runrev.com/mailman/listinfo/use-revolution
>
>
Francois Chaplais
http://cas.ensmp.fr/~chaplais/
http://cas.ensmp.fr/~chaplais/index-e.html