When I write a book, I always imagine who the reader is. Depending on the kind of project, it might be a beginning computer science student, or an experienced engineer starting out with learning a new technology.
Sometimes, it's “myself, as I was a little while ago”. That's how it went with Core Java, which sold a huge number of copies when everyone else wanted just what I wanted too: know how to solve common tasks in a new language. Other books didn't do so well teaching their readers how to develop hierarchies of fruit and animals.
Now I am in the same happy situation with the Scala book that I am writing. There are other Scala books out there, and they are nice books. It's just that they have examples with fruit and animals, and I still don't like those. Even if they show me the mechanics of a feature, they rarely show why I would want to use it. Even worse, unless they are very carefully constructed, the intuition that I have about fruits or animals can lead me seriously astray. So I decided to write my own book.
I find myself referring to my draft when I code in Scala quite a bit, as I need reminders about file handling, pattern matching, or the finer points of traits. Occasionally, a tidbit is in an unexpected place, and I get to move it, since, after all, it is my book.
The chapters are converging nicely, and thanks to modern publishing technology, I can unveil the result incrementally. If you have a Safari subscription, go here. If not, you can get the "A1" level materials for free from typesafe.com here. (A1 is the "beginning application programmer" level from Martin Odersky's Scala levels.) Bugs? Comments? Suggestions? Please leave them here.
I'd like to put in a plug for the technology that makes it possible for me to quickly write and rewrite this material. I write in XHTML, with a simple style sheet that takes care of section numbering, cross-references, notes and tips. Then I use PrinceXML to turn out PDF. It is a great “what you see is what you need” system that gives me control over what I care about—in particular, what is and what isn't code. I could use Docbook and FOP, but that looks far more complex.
PrinceXML is a bit pricey for an individual user, but there is an inexpensive online service, DocRaptor. You make a JSON call with the contents of the document, as a single file with all images embedded as data URIs, and you get the PDF document back. I wrote a script that does the image embedding and that glues the chapters together—using Scala, of course. Scala may not be a scripting language, but it is my favorite language for writing scripts.