Writing A Technical Book: The Stuff No One Tells You

We are finishing-up the final parts of the book “The Essential Guide To Flash Games“. The Amazon release date is wrong, as the whole process is about a month behind. We are sorry for anyone who expected to get this thing next week, but honestly, (HONESTLY), the book is much much better for the delay. I’ll explain below.

Recently I found a ton of great blog posts about why people SHOULD NOT write technical books. All of them are listed here: Lessons Learned from Writing a Technical Book to Teach Programming . This blog post is by a guy named Albert Sweigart who has written an amazing online book named Invent Your Own Games With Python . The book teaches kids and young adults programming using Python as substitute for BASIC. It is awesome. However, while Albert should be commended for his book, his experiences with writing the book are very similar to ours. He, like many of the others, simply found the process much more difficult than they perceived it when they started. The problems mostly come from expectations. You simply don’t know what to expect when you start, and it turns out much different than you ever imagined.

Basically, writing a technical book takes many times more effort than you expect it will take. Basically it all comes down to the rounds of revisions. It goes something like this:

  1. Round One: The basic book idea comes to your head. It swims a round for a long time.You mull it over. To go back and forth over what the subject will be, and finally you come up with something that you think you can finish. My advice, stop here.
  2. Round Two: You didn’t take my advice, OK well, I warned you. Now you write down as much of the book idea as possible and form into something you think others might want to read. If you thought the “idea” part was hard, breaking it down in parts that equal a satisfying whole is even more difficult.
  3. Round Three: You create an informal proposal. This proposal is part book idea, part introduction letter, part resume. You submit this informal proposal to book companies. Most of them will reject the idea, showing you data that says how few books of this type have sold in the past. Listen to these people. However, eventually (if you are unlucky) someone will bite.
  4. Round Four: Write a formal proposal: This is like a massive book outline. It’s an intensive table of contents three levels deep. This is where the problems start. You probably have not planned exactly what will be in the book yet, but now you need to do it. Without any grounded experience in what it will take to write a technical book, you will inevitably bite off more than you can chew because you are excited about the opportunity. (“Sure, we can create 10 full games and write full 40-100 page tutorials about creating each one in four months! No problem”)
  5. Round Five: The Actual Writing part: So, now it has been months since you thought of this idea, and it is time to start writing. The standard process is a two-week turn-around per chapter. TWO WEEKS. For a technical book about games, this means possibly writing a game and the text about that game in your spare time (there is no possible way you can do this as a full time job, it’s more like a way to hone your skills for a regular job) over two weeks. The pace is insane.
  6. Round Six: If you survive round five, the next round comes when the book comes back from the editor with “comments”. These comments are are always helpful, but rarely positive. In effect, they make you feel like you should take 6th grade English class all over again. Remember that informal prose and voice that you established writing blog tutorials? It is not appropriate for a technical book. The editor will let you know all about it. Each chapter filters back one at a time, just long enough for the wounds to nearly heal from the last chapter’s review, before they are opened yet again by another chapter review.
  7. Round Seven: This is the part where you discover if you can take criticism or not: The Technical Review. Remember those two week cycles you had to write each chapter (and a maybe a game too). The Technical Reviewer does not (and by definition Can Not) take that into consideration. No matter what pace you had to write the code and text, the Technical Reviewer tells you what needs to change. The publishing company will find someone who is a total expert in the field. Someone who really knows their stuff. Not in the way you “think” you know your stuff, but in a way that makes others weep with envy. In many cases, what you might have thought was a brilliant twist or idea, concept or algorithm, its thrown back at you as “pedestrian”, “unprofessional”, and “not standard”. It is like the world’s worst code review. Like having an enema using a balloon filled with sulfuric acid and roofing nails. Often, the thought comes to your mind, “why isn’t this guy writing the book instead of me“, and then you realize that “he doesn’t have time when he’s correcting dumb-asses like you.” The problem is, it’s a one-way process. There is no way for you to explain “why” something is done the way it is to the TR. Since the TR is not necessarily an expert on the subject of the book, just the underlying technology, this can be very frustrating. That is, until you realize the TR is just like your audience. His questions are their questions. His comments are their comments. He asks the hard questions so the the future readers will get the benefit of them. So, in reality, what is happening here is not as bad as it sounds. This round is making the book readable and understandable to your peers. This is the round that takes the longest, because in some cases, you have to re-write your code to make it better. And it does get better. Much better. But it is still a very painful process.
  8. Round Eight: Copy Editing: This is where someone who knows the standards of the book company and publishing industry tells you that your writing cannot be consumed by other humans and much must be re-worked. This would be a wholly negative experience if it had not been for the technical review, which has already broken you down into a quivering mass.
  9. Final Review: This is the last round. You look at the final product and add a comma or period here or there and hope for the best

So after all this, what do you have? Well all of these rounds of revisions are designed to make the book worth reading. In reality, each one is designed to refine the book more and more into something that will be useful to developers. The Proposal let’s a professional tell you whether your idea for the book is something that will even be viable in the current market. The Editorial Review let’s someone who is technical, but doesn’t necessarily know the material, read it and tell what doesn’t make sense. The Technical Review gives you the chance to iterate your code and descriptions and make them much better for your readers. The Copy Editing puts fine sheen on the final product. And in reality, the final product is what matters the most.

So what does  the author get out of the process? Well, you learn a lot about yourself. You learn the meaning of hard work. You learn what is important to you as an individual (family, friends, free time). You learn to check your ego at the door and take criticism as it is intended. You get better at what you do, and by extension, your readers will get the benefit of that experience. For example, the code-base we have created for the book has already cut-off about 30% of the development time for some of our new projects. However, is the actual writing process something we would do again? Was it worth all the time and effort put into it? We’ll be able to tell you in a couple months.

Leave a Reply