The Documentation

[Peter Alcibiades]

What is missing exactly?

The dictionary is a pretty good version of a man page. Dan's book is ok at the 
level of 'how to think like a computer scientist'  - simple how to get 
started.  Very nice as far as it goes.  Needs a second 
edition. The pdf is ok also as a printable version of the dictionary with a 
few more examples, assuming it ever gets finished.

There are two things missing, or rather, there is one thing missing, but it 
comes in two flavors.   One is the equivalent of Dive Into Python, 
which early on contains the immortal line 

"You know how other books go on and on about programming fundamentals and 
finally work up to building a complete, working program? Let's skip all 
that."  

This is the sort of book that says, you already know about classes, here is 
how they work in Python.

The second is the equivalent of Hetland's Python book.  It is step by step, 
this is how you do certain things, using various bits of the language, with 
an account of pitfalls.  Starts simple and moves you through writing real 
applications.

Both are the reverse of the dictionary:  they both start with something to do, 
and then show how to combine different bits of the language to get it done.
  
The Perl book Minimal Perl is about halfway between these two.  Chapters 
like, why Perl is a better awk.  So start from an assumed knowledge and then 
show how Rev does this particular set of tasks, that the known language was 
designed to do, but does it better.  Again its in reverse, it goes from 
problem to multiple bits of the language.

Not that I'm being hung up on Perl, Python or Ruby - these are just well 
regarded examples of docs.

Getting to be a beginner in Rev is easy.  Getting to be a sophisticated user 
in Rev after that is a Zen like experience.  You go to live with the master 
who attacks you at random intervals, whatever you are doing, for no reason.  
Eventually, you hesitate before entering a doorway.  The master emerges and 
bows deeply.  Son, you are getting there, he says.

The priority ought to be:  One, finish what you started.  So either trash the 
pdf or finish it, don't just leave it there twisting in the wind.  

Two must be, the reverse dictionary - here is how to do specific things, using 
various parts of the language together.  The tutorials are a start but only a 
start.  Its a lot of work - Hetland's book is amazing, and Mark Lutz' book 
even more so.  But I really think that 400-500 systematic pages of this is 
what you need if you're to attract a lot of new people who are not oriented 
to Zen based learning.   If you are doing Dive into Rev for the experienced, 
then it can be shorter.  I don't know which should have priority, Dive, or 
something introductory.  It depends on which market you're going after.

Whether the less experienced new people are worth the trouble, you'd have to 
know more about the numbers for Rev to assess.

I'm not complaining by the way.  Personally I don't mind the odd frustrations 
and find them well compensated by the sudden blinding flash of illumination.  
In fact, I sort of like the mental exercise. But a lot of people are in more 
of a hurry, and if you want to get to them, you have to offer them something 
like that.

Peter