Writing the Scala Cookbook for O'Reilly - February, 2013

By Alvin Alexander. Last updated: June 4, 2016

I've been keeping notes about the process of writing the Scala Cookbook for O'Reilly, and I thought I'd share a few of those thoughts here today (early February, 2013).

Current status

I finished writing the first draft of the book in the first week of November, 2012. At that time the O'Reilly folks created a PDF version of the book, and several reviewers started in on the review process. We ran into a couple of issues during the first review phase, including some delays around the holidays, so we added some more reviewers in January, 2013.

My current plan is to finish the current editing/rewrite process by March 1st, and then the book jumps into the production process. My understanding is that I'll review the book a few more times during that process, but that should primarily involve production and layout issues.

Reviewers

I've never been through this process before, but one thing I've seen with almost all reviewers is that this is a very big book -- it covers Scala, actors, SBT, etc. -- and only one reviewer came close to providing comments on the entire book.

The review process itself has been interesting; every reviewer has their own style. Nice reviewers write something like, "IMHO, I would do XYZ here." Other reviewers write things that border on, "This sucks," or "This is stupid." (Comments like these make me think of the end of the movie, While You Were Sleeping, when Jack says to Peter, "You suck," and after pausing for a moment, Peter replies, "My suit sucks? Or I suck?" Or the old SNL skit: "Jane, you ignorant slut.")

I've written thousands of pages of documentation and requirements specs, and I learned many years ago to treat those comments the way people talked about Steve Jobs: You have to separate the message from the messenger. (In most cases the reviewer is right on a technical matter, I've done something wrong, and in some cases I researched the problem and found that I was correct.)

The important thing is that their comments have been helpful. Besides having the reviewers point out my mistakes, it's nice to see different perspectives. When some of the comments have overlapped, I'd see one reviewer say "X" and another reviewer say "Y" about the same thing. (In a simple example, some like for/yield, others map, for example.)

This is where it gets really interesting: Because Scala can be used as both (a) a functional programming language and (b) an object-oriented programming language, I've received really interesting comments from both the FP and OOP camps. For instance, one reviewer with a strong FP background asked why I was covering certain topics in the Classes chapter. The reason I did: The topics are relevant for OO developers. (I'll share more about this in the future, but again, the review process has made for a much better book.)

Technology changes fast

I proposed the Scala Cookbook to O'Reilly some time last spring. (See "So you want to write a book for O'Reilly" to learn about the proposal process.) I believe I then formally started writing the book in June, 2012. Since I started writing it, Scala has moved from version 2.9.1 to 2.9.2 and 2.10 (now 2.10.2); and SBT, I don't remember, but I think I started with version 0.10. At the time of this writing -- February, 2013 -- I've updated all of the examples to the latest versions of all these tools.

Eating my own dog food

As I've been writing the book, I've also been writing my own Scala applications. I wrote a couple of Swing apps (the Blue Parrot, for example), some web apps, shell scripts, and of course SARAH, which makes extensive use of Akka Actors. As I've been doing this, whenever I've run into a problem I've either made sure I covered that problem in the book, or added a recipe to demonstrate the problem and solution.

My philosophy on developing software, and this book

My philosophy on developing software projects can be summed up this way:

Get 'Version 1' out the door fast.
Absorb feedback from the customer.
Iterate like crazy to improve the product.

Writing this book has been like that, except that Version 1 (and Version 2) were only shipped to my editor and the reviewers. So I got Step 1 done, they've given me feedback, and now I'm iterating (editing/rewriting) like crazy.

Working with O'Reilly

Working with the people at O'Reilly has been very easy, no complaints here.

As you've probably heard, a good editor helps to keep the author sane, and my editor with O'Reilly has certainly done that. (Personally I was most nervous when I hadn't written a word, and realized I was about to write 300-400 recipes that would probably cover 600+ pages. Okay ... I may have lost it once or twice later as well. :)

The only complaint I have is that I started writing the book using Microsoft Word on the Mac, which was a mistake. I would have been much better off using DocBook. This complaint has nothing to do with O'Reilly; it has to do with the following message, which I see several times every day:

Microsoft Word on the Mac (not responding)

Thanks to Richard Dallaway on Twitter, I'm reminded that O'Reilly now supports Atlas.

Summary

If you've ever wanted to write a book for O'Reilly, or you're interested in the progress of the Scala Cookbook, I hope you've found these comments interesting and helpful.