How to Write a Technical Book

Currently my nights and weekends are spent working on the second edition of Programming F#. First of all, let me thank any of you who have read the first edition. Hopefully you enjoyed it.

Revisiting my old work has not only given me a chance to not only correct some errata, but also an opportunity to reflect on the whole book writing process. (Which started for me in the summer of 2008.) This post will serve as my mini-guide and scarecrow for anyone who is considering writing a technical book.

How to Write a Technical Book

Step one: don't. Whoever told you writing a book was a good idea lied to you. Whatever misconception you have about being a famous and respected author is also incorrect. I'm not trying to be ironic or cute here, I actually mean to tell you that you shouldn't write a book.

Start a blog. Go on a speaking tour. Write the world's greatest tutorial/website for your technology. Start a podcast. Do whatever it is you can to get your message out, but I urge you not to write a book unless your motives exactly align with what you will actually get out of the experience.

My motivation for writing Programming F# was to get the word out. I was at Microsoft working on an amazing new programming language, and I wanted to make sure that programmers showed up to the F# party.

While I knew that I wasn't going to make a lot of money, I thought that I would be able to earn a a tidy sum from the book. Perhaps enough to put a down payment on a house! Or at least zap those college loans floating around.

Read the following sentence slowly: writing a book will take more time and you will earn less money than you think. Now, after you have adjusted your mental model of expectations, reread that sentence at least two or three more times.

Fame

On the book shelf next to me I have about 100 books. Of those, about 50 are "technical" and on the subject of computer science, programming languages, technologies, etc. Of those books, I can name maybe 10 authors. (And I suspect for most people 10/50 authors is very high.)

My point is that while the author of Enders Game or Twilight is an important detail, in the technical book world it is not. People are going to buy Essential Microsoft SQL Server 20XX regardless of who wrote it, as long as the XX is the most recent release. I don't want to sound too much like a curmudgeon here, but I'm sure people will be interested in buying a book on F# 3.0 regardless of whether or not I write it.

So if you have big hopes of starting your literary career with that great Java book you have been planing, I'm sorry. But you are just the source of the product for a publishing company.

Fortune

Another thing to keep in mind is that you won't strike it rich either.

Books, like most other creative medium, pay based on royalties. You will earn something like 10% of all profits from the sale of your book. So, if your book makes its publisher $1,000,000 in profits then congratulations! However, not many books are going to sell that well. In fact, not many books even pay out past their advance.

Programming F# has done (what I would consider) exceptionally well. In fact it's even been translated to Japanese. However, I did the math and I would have been better off working at Taco Bell than writing for O'Reilly. (OK, I didn't actually do the math and can't say this for certain. But, I think at Taco Bell you would get free food, so I think the advantage is in Cheesy Gordia Crunches.)

If you are stubborn enough to avoid my advice and sacrifice a year of your life, then please read on at your own peril.

Obtaining a Publishing Deal

The first step of writing a technical book is getting a publishing deal. (Actually, self-publishing is super easy to do these days - especially if you are just targeting digital distribution.)

While being a "technical author" means that readers don't care who you are, this actually works in your favor because publishers don't care about you either. That is not to say that publishers don't treat their authors well, I actually love my O'Reilly task masters. It means that technical authors don't have to be a household name, they just have to be able to deliver a good book.

Every technical title published has a shelf-life measured in years if not months. So if you have a timely idea on a new technology publishers are eager to hear from you.

The story behind Programming F#

When I decided I was going to write a book on F#, I was extremely nervous. First of all, I had never written a book before and second I have never been particularly gifted with written word. Nevertheless, I put together a small proposal and emailed it to O'Reilly.

I was expecting a rejection with the intent on getting the ball rolling. Perhaps they would say I need to blog more to establish some writing chops. Or perhaps to take on a co-author who had some writing experience.

As it turns out I got a response the next day to the tune of:

"Hey Chris, this looks good. Why don't you change X, Y, and Z and I'll get this approved next week. Have a nice weekend."

That's it. As it turns out, O'Reilly was looking for someone to write a book on F# and I happened to fit the bill. Working on the F# team at Microsoft probably sweetened the deal. (Programming F# was actually the second F# book in the works at O'Reilly, the first one never got published; but I'll save that bit of F# lore for another day.)

So you have a publishing deal. Now what?

What Type of Technical Book

In college a room mate of mine purchased an 800-page book on XML. Do you think the subject of XML requires 800 pages of exposition? Well, the book's six authors did. Programming F# on the other hand, clocked in at around 380 pages.

One aspect of Programming F# that received the most criticism is an aspect I am the most proud of: it is short.

At the start of the project I set out to write a concise book about the F# programming language. Not the .NET runtime, and certainly not WPF application development using F#. I set out to write a book about the F# programming language and left the subjects of databases, UI development, and XML to other authors.

This brings us to the first and most important thing to consider when writing a technical book: the type of book you are going to write. A summary like "web programming in the YFL language" is not good enough. Will your book be a reference book, dense with fact and requiring lots of flipping through? Or will it be a tutorial, walking the reader through and end-to-end experience?

There certainly isn't a right or wrong type of technical book, but it is paramount to understand what the book is trying achieve before you write anything.
The Writing Process

Once you have the purpose of the book in mind, how do you actual go about and write it? I would suggest using the following organization.

Table of contents

Create a new document titled "Table of Contents" and in it put a billeted list with three levels of indentation. At the highest-level bullet are chapter headings. Below that are your H1 and H2 headings.

At this phase of the book you are super-excited and raring to just dive in and start writing. You must resist this urge as long as you can. The "Table of Contents" document is the master plan for your book and the only thing keeping it focused and coherent. (Opposed to a bunch of random anecdotes, facts, and examples.)

Once you have a clear picture of the entire book, down to the H2 section you then need to create a schedule to keep track of the state of the overall project.

Status sheet

Create a spread sheet titled "Status" and have a row for each chapter of the book, including the foreword, introduction, and possibly the index. The columns should be used to track the state of each chapter as you progress along from "outline" to "draft" to "tech review" and so on.

Whenever I moved a chapter of the book past a given phase, I would put an X in the cell which would then trigger conditional formatting to paint the cell green. This way I could see how far along the book was (and what needed the most attention) at a glance.

Q - Ch12 - Reflection

Finally, start writing the book. I recommend creating a document for each chapter of the book and naming the document with a letter to control sort ordering. (For example "A - Foreword", "B - Preface", "C - Ch01", and so on.)

This convention might seem like a strange optimization, but I assure you that the number of times you will need to quickly locate an arbitrary part of the book will be non-trivial. And having the sections of your book in the correct order will be invaluable.

The Writing Stages

Once you have the software setup to actually write the book, next comes the iteration. Depending on your book project there might be a different number of stages. Since I was a first-time author O'Reilly hired a developmental editor for the project, Brian MacDonald, who was awesome.

Outline

When you finish the outline you will think that the book is clearly organized and you will have a firm grasp of the material. You will also think that you did such a good job organizing the book that it will take less time than you thought it would. You are incorrect.

First draft

You will work on the book for months grinding away at each chapter. You will avoid parties, movies, and any other social outing because you will be busy working on the book.

The day you finish the first draft will be the first day since you started writing that you are actually proud of your work. You will think that the first draft is the best thing you have written in your life. And, hopefully, it actually is.

Second draft

After finishing the second draft you will realize just how terrible of a writer you are. You will also curse the Word grammar engine for missing that one, common error you make all the damn time. You will be proud you never showed the first draft to anyone.

Unfortunately, little of your first draft was salvageable, and the parts that were contained insultingly poor punctuation.

However, you will persevere and finish the second draft. You will have learned from your mistakes and shaped the book into something even better. At this point you almost want to mail the manuscript to your college English professor to show them how accomplished you are.

Post developmental editor

After seeing your development editor's corrections you would feel sorry for them if you didn't already feel so humiliated. You think that you don't need someone pointing out that sentences are supposed to have verbs. Or that "receive" isn't spelled like "recieve", but evidently you do.

The corrections will be so painfully obvious, so gloriously bad that you are shocked that you even wrote it that way in the first place. You will question whether you sent them an older version of the file, or perhaps some gremlin snuck into your computer and altered the files.

Either way, you know what you have to do so you just revise the text again. And this time when you are done it finally feels like a completed book. You print out all 200+ pages and go over every single page with a red pen, several times.

Now the book is done except for a technical review, where people will compliment you on your insightful examples and clear exposition.

Post tech review

You will contemplate purchasing a firearm. Perhaps several. And trying to track down the insulting bastards who chose to troll you while writing your own book.

"No, it doesn't work that way!" you will shout at your monitor while you read their feedback. Eager to prove your point, you will try some experiments. And sure enough, you will realize that you were wrong. In fact, more than wrong. The foundation of your entire understanding of computers will rendered invalid.

The pain of rephrasing large swaths of text won't sting nearly as much as the realization that you have been misspeaking about your favorite technology for perhaps years.

Final edit

After seasons of work you are finally done. You take a deep breath and finally relax. Knowing that your hard work has been completed. People will finally be able to read your hard work, and understand what you hare sacrificed for.

Amazon feedback

You will read your first review on Amazon.com, and want to react like this. Your readers will tell you that the they liked some other book better; or instead wish you had written a different book.

*Bonus* Second edition draft

When you get the offer to write the second edition you will feel uneasy. You will know just how much work went into the first edition, but feel assured knowing that you wrote a great book the first time.

While correcting known errata you will find grievous technical errors and sins against the English language hidden in the book's text. You will be shocked that no one has found these errors sooner, and terrified at the thought of how many more you will discover.

Even worse, your task isn't merely polishing existing text, but rather attempting to add updated content without breaking the existing flow/theme of the book. And, just like last time, you are writing about a subject matter that is constantly evolving and not even in beta stages...

Shipping

If you aren't somehow dissuaded by this blog post and succeed in surviving all of the stages of writing, you are now the proud copyright owner for a book. Configurations!

The thrill of seeing your own book on store shelves never gets old, and neither does meeting people who have read your book at developer conferences. There is one thing to watch out for though: book signings.

One thing you need to be prepared for is when people ask you to autograph their book. I know what you are thinking, "Sure, I'll just put my name, write a cute message, and it will be quick." I wish that were the case.

Instead, people with names you have never heard of, names which you have no hope of spelling correctly, will ask you to make it out to them every time. And that "cute message" will be impossible to come up with on the spot. Instead, you will just try to scribble their name just illegible enough that they can't verify you got it wrong and go with one of several catch phrases.

If I ever write another book I'm going to come up with a solution to this problem...

Anyways, go forth and write books about things you are passionate about! Don't say I didn't warn you that the process would be a pain in the ass, but it is worth it. I look forward to reading it.