Learning how to write a technology book (for O'Reilly)

A fun part of writing the Scala Cookbook has been learning more about the process of thorough writing, and doing more research about topics than I’ve ever done before.

The process goes something like this: For the next 24 hours I'm working on editing the “XML & XPath” chapter, which was originally written a few months ago. For these 24 hours, I let myself “love” processing XML with Scala.

I try all sorts of experiments with Scala/XML code, and read dozens (maybe hundreds) of web pages about problems developers are having, and potential solutions. During this time I try not to leave any stone unturned, and if one clue leads to another, well, I just keep following them, trying to find the “best” way(s) to solve each problem, hoping to add one or two extra nuggets that will make an important difference to readers of this chapter.

Tomorrow, and the next day

Then another interesting thing happens: Tomorrow I forget all about XML, and “love” SBT. I do all that research and perform all those experiments on SBT, again trying to leave no stone unturned.

Then the next day I forget about SBT and “love” some other piece of Scala technology.

For each chapter, I think to myself that I want a developer in a bookstore to pick up the Scala Cookbook, thumb through that chapter, and think, “Man, this chapter alone is worth the price of the book.” Frankly, I don't know if I'm there yet on all the chapters, but it's getting close.

A note here on the “love” part: Like everyone else, I have a lot of other things going on in life, and I find it helps if I “give myself permission” to spend all this time on one subject (and all this time on a book I hoped to have completed in December or January).

Writing for O'Reilly

To their credit, the folks at O'Reilly have been very patient with me. Whenever I think too much time has passed, they tell me to take my time and write a great book, everything else will take care of itself.

Being a first-time author, I originally wanted to have the book released around the New Years holiday (when people had extra money, or were spending it more freely), but looking back at the manuscript I submitted back in November, I have to agree, it was crap. The problems and solutions were okay, but there was no depth to them. I'm much happier with what I have now.

Writing these recipes is different than writing a blog post on this website. When I write a post here, it usually reflects a problem I've just run into, and how I solved it. The book is much deeper than that, and among other things, shows alternate approaches, better examples, and more research behind the problem/solution.

Also, although we've had some delays because of issues with reviewers, the review process itself has been incredibly helpful. The best reviewers have pointed out my errors, suggested alternate approaches, and provided better examples.

Working from home

Working from home has also been interesting. I've worked from home for several years now, but lately it has gotten boring, and I long for the company of working with others, as part of a team. This has made me more distracted than I was a few years ago.

To fight my feelings of distraction, I've recently started the mornings like this:

First, I work a little on this website to get my brain going.

Next, I work in 20-30 minute increments, like this:

1. Work for 20-30 minutes.
2. Take a short break, wash the dishes, clean a little, check social media, whatever.
3. Work for 20-30 minutes.
4. Take a short break.

I continue that cycle until I really get into the work, at which time the breaks seem more annoying than helpful. At this point I usually work several consecutive hours without break.

To enforce the cycle, I set a timer on the microwave in the kitchen. Although I wrote a timer application long ago that I use when meditating, I find that using the microwave timer is better because it forces me to get up.

(On my really bad days I find that it's useful to count how many twenty minute work segments I've managed. To do this, I make a series of tick marks on a piece of scrap paper. Twelve tick marks equates to four hours of real work, and on those days, I try to be happy with that.)

The other thing I do is print the chapters and take them to a coffee shop so I can review them there. I could edit them on my laptop, but for me, it's nice not to look at a computer screen for a while.

Summary

My degree is in Aerospace Engineering, and the thing I thought was best about college is that I “learned how to learn”. With this book, I feel like I've learned a lot about the process of writing a technology book. For my personality, the biggest thing has been giving myself permission to indulge myself in each topic, and then make it the best I can.