Documentation and Parental Cruelty
palcibiades-first at yahoo.co.uk
Sun Jun 24 03:22:31 CDT 2007
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
"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.
More information about the use-livecode