[ruby-talk:21420] Re: Ruby/objects book in style of The Little Lisper

On 20 Sep 2001 06:19:44 +0900, Brian Marick wrote:
> I fell in love with Lisp in the early 80's. Back then, I read a book called 
> The Little Lisper, which I also loved. It's an interesting book, in that 
> some people love it and some people hate it. It crams a lot of information 
> into a deceptively simple dialogue style, and always skates just this side 
> of being too cute. (At least, those who like it think so.)
> 
> A while back, I started thinking of writing a book about objects in this 
> style. It would get as deeply into objects as The Little Lisper does into 
> recursion and lambda. So I want to start at the beginning and end with 
> advanced metaclass hackery and things like first-class continuations. Ruby 
> would be an ideal language for the book, even better than Smalltalk, so the 
> tentative title is A Little Ruby, A Lot of Objects.
> 
> The question is: can I pull it off? To see, I wrote the first chapter, 
> which you can find here:
> <http://www.visibleworkings.com/little-ruby/Chapter1.pdf>
> If you also liked The Little Lisper, I'd be happy if you took a look at my 
> chapter and gave me your opinion:
> 
> 1) I'm trying to come close to TLL's gently whimsical tone. Have I got it?
> 
> 2) Does the chapter show evidence that I can make a book build in the
>     way that TLL does?
> 
> Please be frank. Writing in this style is surprisingly hard, so I want to 
> stop now if I'm not up to it.
> 
> Thank you. If I decide to continue, I'll ask (on a separate mailing list 
> that I'll set up) for topics/hacks to be sure to include.


This is my very different attempt at a computer language tutorial
written nearly 10 years ago:-

ftp://ftp.funet.fi/pub/languages/C/tutorials/sawtell_C.tar.gz

Like your work it attemps to be light hearted and whimsical, but in a
rather different way.

The problem with whimsey in technical writing is that it is _extremely_
difficult to find the correct place for the line which separates "In
Jokes", for an understanding of which you have to have a full
understanding of the subject matter and are meaningless in a tutorial
for new learners, from the gentle leavening of otherwise solid prose.
Also I'd just like to say that it is even harder to to pitch one's
humour so that it is humourous the world over and inoffensive to all
cultures without it being horribly corney.

If I might just make a comment before you really get going on your book.
I have found that my readers appreciated that my prose did not talk down
to them, was written in such a way that it was understandable by readers
worldwide who learnt English at school rather than on Mother's knee,
avoided overt jargon and acronyms, and all the examples were fully
tested and working programs.
If at all possible make the program itself produce the text output which
goes into the manuscript. You can do this if you use either groff or
LaTeX for document preparation Finally I gather that the most
appreciated point is that my prose was very carefully edited to avoid
making the work a full sized door stopper. Thus I like your idea of a
_Little_ book. You will sell more because they will be less costly than
the others.

Since my little literary effort I've realized that I failed with the
examples. I didn't really get the idea back then that it is really
important that the examples are as true to life as it is possible to get
in a text-book, and - most important - follow a continuous thread. (
imho The Pickaxe Book, and many others fail miserably here ). Ideally,
one want's to end up with a slightly useful application at the end of
the book.

I think that a "Learn to Program a Computer with Ruby", rather than
"Learn Ruby" would be a great kind of book. Take care not to drop the
readers into the deep end and drown them before they can swim.

Make it very clear right at the beginning of the book that you don't do
kid's homework for free, or you will find that your telephone will ring
continuously and your mail boxes will be filled to overflowing with
plaintive pleas from the lazy and less intellectually able.