Documentation and Parental Cruelty

[Peter Alcibiades]

Is there a model  or models for documentation?

Yes, there are several in the world of Python.  Hetland's book

"Beginning Python from Novice to Professional"

is a model of how to do it for quite a wide range of people. It has the 
quality which Judy Perry speaks of:  nothing is introduced without being 
explained clearly - variables, classes, whatever.  Hetland's book also is to 
some extent a cookbook or thesaurus.  It shows you not only what the language 
does, but it shows you how to do some well chosen things.  A professional new 
to Python would probably not find it too condescending, but someone fairly 
new to programming could also pick it up and get up to speed.  They would 
just spend their time a bit differently on different parts.  The basic bits 
are terse but very clear, and you quickly move on to the interesting stuff.

This is the kind of documentation that is either missing or only available in 
fragmented form for Rev.  To be fair however, Python needs it a lot more than 
Rev does.  One of the joys of Rev is how little documentation it can get away 
with.  But if Rev were to embark on just one documentation project, this 
would be one reasonable model.  Its a massive undertaking however.

There is Dan Shafer's book.  Perhaps the Python analogy would be the well 
known "How to think like a Computer Scientist".  Very gentle and also very 
well written.  I don't think its any better than Dan's book which is very 
good as far as it goes.

There is also Guido van Rossum's book on Python, and "Dive into Python".  
Those are much more oriented to strong programmers who want to get started 
fast.  There is no analogue to either for Rev that I've seen.  They are 
fairly brief, get up to speed with the essentials fast., assuming you know 
other languages well, very systematic.

"Python in a Nutshell" is a reference manual - a bit like what Rev started 
with their pdf document a year ago but more detailed.  Does Rev really need 
this level of detail?    On the other hand, that pdf project really ought to 
be completed.

"Python Cookbook" is probably the model for the most useful second thing Rev 
could add to its documentation.  It is a reverse dictionary if you like.  Not 
documentation of the language, but documentation of meanings, how to use 
various bits of the language to do things. There is quite a bit of this 
available for Rev, but it is very scattered, and it would be much more 
accessible were it all in one place properly edited.  Maybe if Rev were to do 
just one thing in addition to finishing the pdf, that would get most return 
for least effort, it would be to put something like this together from the 
existing scattered stuff, with supplementary material and structure.

I think its a mistake to be too demanding about it for Rev.  Yes, there are 
examples of things that would enormously improve its accessibility.  But no, 
what it has is not completely inadequate.  You are never going to get away 
from headbanging when you learn a new language.  However, there is no doubt 
that better, or at least more complete and varied, documentation could have a 
role in increasing accessibility.


Peter