Clay Allsopp

Writing a Programming Book

Dec 12, 2012

It's barely past midnight on Christmas, and there's a book on my lap. Its black glossy cover smears with every brush of my fingers. Front and center, the lone graphic is half of a sliced, juicy grapefruit. That “new book” smell eases from the unworn pages. The book is "Beginning iPhone Development" by Dave Mark and Jeff LaMarche, and it changed everything for me.

So here I am years later, just finished writing my own iOS book. It's hard not to wonder if there's an aspiring programmer who might connect with my work like I did with Dave and Jeff's. That maybe my little RubyMotion book might show them, "Yeah, it really is this easy to build something cool"; but then again, almost every other book I read failed to do that.

There are as many different ways to write a programming book as there are programmers. There are those reference tomes, the kinds of things that sputter dust when you manage to wrangle them onto the desk. Then there's the cookbooks, textbooks, the career guides, the list goes on. But growing up I collected dozens of the venerable "Getting Started" genre, and that's what I wanted to do for RubyMotion.

Writing that kind of introduction is tricky. You risk stonewalling your readers to the point where they flip the table and walk away, never giving the technology the chance you believe it deserves. In my experience, those books usually have an authoritative or even aloof tone, and focus heavily on demonstrating "the right way." But the right way to engineer a project might be the wrong way to get excited about it.

I made my priority to get something cool, but simple, on the reader's screen as fast as possible, and then worry about cleaning up any mess a little later. For example, iOS books usually start off with how to use Interface Builder or setting up UIViewControllers, but that's just so much overhead to getting anything interesting on the screen. I bucked tradition and began with code I'd never use in production: adding blue boxes straight on the app's UIWindow. It's a bit dirty, but then we can quickly jump into buttons, animations, text boxes, and really start to make fun apps.

Technical reviewers noted that exact decision, and then expressed their delight at how well it actually worked. And to me, that's what a "Getting Started" book is about: here's the bare-minimum, and now here's cool stuff we can do with that. As long as you keep that thesis in mind, the rest of the writing is just filling in gaps.

So, if you're in the market to very quickly become up-to-speed on iOS development, then join me in making cool projects with RubyMotion: iOS Development With Ruby. Or if you think this is all a rubbish idea, ping me on Twitter.

Enjoy this? Follow for more on Twitter