How to Write a Book: Introduction

Jun 11, 2013 at 5:25PM
Caleb Doxsey

In September of 2012 I self-published the book An Introduction to Programming in Go through Amazon (physical and ebook) and online. I thought I’d write a series of posts on how I did it.

Why Write the Book?

In the spring of 2012 I was considering teaching a programming class to some high school aged homeschool students at my church.

I have strong beliefs when it comes to programming education. We send 18 year olds off to scale an uber-expensive computer science ivory tower where programming isn’t so much taught as merely assumed. What’s worse the education they receive has very little to do with the day-to-day activities of actual developers. (And as much as Google pushes it knowing how to write a Binary Search tree from scratch, or figure out Big O notation, is not actually that useful)

The nature of our economy is changing right before our eyes and as a society we are failing to adequately prepare our children for those changes. We built an education system which makes factory workers and then we got rid of all the factories. We need programming to stop being an elitist profession and to start being a rudimentary skill everyone is exposed to at some point. We need middlebrow developers.

Programming is hard for (at least) two reasons:

  1. It’s very different than anything most people are accustomed to doing. Like Algebra you have to learn a new way of thinking about problems; once you’ve learned it it seems obvious, but the process can be very difficult for many people.
  2. There is a tremendous amount of rarely explained background knowledge largely unrelated to actual programming which sets up a formidable roadblock to getting anything done.

    Consider for a moment the ubiquity of computers for a kid growing up in today’s world. Phones, televisions, cars, laptops, tablets, … He’s surrounded by them. But I would argue a kid today probably knows less about how these devices work than his grandparents.

    And there’s nothing wrong with that per-se. It’s fantastic that we’ve developed devices which hide the unnecessary details from a user and allow them to do the things they want to do without having to be exposed to the underlying implementation.

    But programming forces you to know the underlying implementation. The way we write code hasn’t fundamentally changed in 20-30 years, so to have any hope of learning how to program you’ve got to learn how to use a computer as it was designed 20-30 years ago. You have to know about text editors, terminals, commands, operating systems and file systems: all things you’re not exposed to with a modern computer.

Ultimately the class never happened, but this book was meant as the textbook for that class. (And it was never really meant to be independent. I think mentoring is a critical component of the learning process)

Go was chosen as the programming language because it purposefully turns its back on many of the modern language design shibboleths of our age. It’s not clever. And for a first year programming student clever is just about the last thing you want. It also runs in Windows and OSX, has a solid toolset with good documentation and it doesn’t reinvent the wheel when it comes to software process. If you can learn to program in Go you’ll be well positioned to program in just about any other environment.

Process

Writing a book is hard and not for the faint-hearted. It takes a serious commitment of time and energy (on the order of months of dedication) with little payoff at the end. (It’s highly unlikely you’ll make a lot of money writing a book) It also requires a great deal of self-discipline. Working for yourself is hard.

In my case I was blessed (or cursed depending on how you look at it) to be unemployed for 3 months in 2012. I had ample free time and this book was as much about proving to myself that I could write it as it was about producing something worthwhile.

I enjoy writing but I’m not a particularly good writer. I’m very slow and I put a great deal of thought into what I’m trying to say. And “say” is the right word here. The spoken word is primary for me and I often find the written word a difficult medium to work in.

I started with a basic outline and then immediately started writing. Sometimes I’d only finish a paragraph or two. At other times I’d do an entire chapter in one sitting. And I rewrote. A lot.

While writing I always tried to keep my reader in mind. What was he thinking at this point in the book? What might seem confusing? My book doesn’t do a lot of handholding - as I said before it was not intended to function by itself - but I wanted everything you needed to understand to be available to you. My primary model here was a logic textbook.

I used a few different editing techniques. I’d read straight through (often aloud) and then backwards (helps to find spelling mistakes). I did a lot of consistency checks. Things like is Go “Go” or “go”, or am I consistently using “You” rather than “We”? I also tried to verify the internal consistency of my references. (If I say see chapter 3, is chapter 3 really where I want you to go?) This was particularly important early on when I was adding, removing and rearranging chapters. Editing is really hard to do well. After reading the same stuff over and over again you just can’t see the mistakes anymore. If you can, get another pair of eyes on it.

Despite my best effort there were still a lot of mistakes. But here’s something to keep in mind: it doesn’t have to be perfect. I read a lot of books on my kindle and there’s been a marked decrease in editing quality in the last few years. Even highly polished, super popular books by well known authors have mistakes, and I’m starting to suspect that people’s tolerance for mistakes is a lot higher than it used to be.

Overall I’m happy with how it turned out. Feedback has been mostly positive and the 3 stars it got on Goodreads is probably a fair characterization of its quality. I didn’t write a masterpiece. But it also only costs 10$.

Next time I’ll talk about some of the tools I used.