Programming with Types RTM

Programming with Types is going to the printer today and should be available as a print books in a couple of weeks. I figured I'll write a blog post about writing the book for the occasion. I wrote in a previous post how the book came to be, but didn't really cover the implementation details.

Prototype

I started writing the book before even thinking about publishing. The best way I can put it is I felt I had a book in me. I learned a lot of material during the past few years and I wanted to synthesize it in book form, hopefully useful to others. I created a repository on GitHub, outlined the topics I wanted to cover, and for a few weeks I spent a few minutes every morning over coffee filling in some of the sections. As a fun fact, the original title of the book was Practical Types. This was August 2018.

Pitch

In September, when I realized I am indeed writing a book, I figured I should pitch it to publishers. No harm in trying. I reached out to O'Reilly and Manning. O'Reilly promptly dismissed my proposal. Manning put me in touch with a publisher and we scheduled a couple of calls to discuss some of the details.

I got some invaluable feedback even from those initial calls - suggestions on how to improve the table of contents, how to make the book more accessible to readers, how to split topics up into chapters based on the difficulty of the topic and so on. After those initial calls, I was fortunate to get a contract.

Contract

The most important part of the contract is the manuscript delivery. There are 3 key milestones, each 4 months apart. The milestones were:

• Deliver a third of the manuscript no later than February 2019.
• Deliver two thirds of the manuscript no later than June 2019.
• Deliver the complete draft of the manuscript no later than October 2019.

I got paid an advance delivered in two batches: the first half upon delivery of the first third of the manuscript, the second half upon delivery of the complete draft. I will also be getting a percentage of sales of the book. The way advances work, the book needs to sell enough to cover the advance before I will receive any more royalties. I will pause here to say that I don't expect to get rich off of this book. Another fun fact I learned is that most books don't even recover the advance, so if you ever want to write a book simply for the money, you might want to reconsider.

Training

After the paperwork was signed, I was assigned a developmental editor and the first thing we did was a new author training where I was introduced to the Manning method of writing books. Since Manning has been publishing high quality technical books for many years, they have a set of best practices authors are encouraged to follow. These include things like starting with a concrete example then generalizing to the abstract, using figures to better explain things, tracking the prerequisites of each chapter and making sure there is a smooth progression and so on. These trainings were delivered by my editor over a few Skype calls.

Feedback Loop

Throughout the writing stage, I worked closely with two editors. After completing a draft of each chapter, I would upload it and get the initial round of feedback from them. The developmental editor would make sure my writing is up to par and the text makes sense; the technical developmental editor would keep me honest for the technical aspects of the book, and make sure I didn't mess anything up there.

With each milestone (1/3, 2/3, 3/3 of the book), Manning also conducted an external review with around 20 other volunteers who would go over the manuscript and provide feedback. When the external feedback came in, we analyzed it for trends to identify areas of improvement - for example, if multiple people were saying a particular section is hard to grok, it was clear it needed improvement.

As the book was nearing completion, I also got a reviewer for the code samples. He made sure all the code makes sense, compiles, and the GitHub version matches the book version.

Writing a book is definitely a team effort. Without all the great feedback I received it would've been a pretty crappy book. Many thanks to Michael Stephens, Elesha Hyde, Mike Shepard, German Gonzales, and all the other great folks at Manning for all their help. I'm also grateful to all the external reviewers for their time.

I learned that the first chapter is the one that usually requires the most refactoring, which was definitely true in my case.

Writing

Because I started with a list of topics I wanted to cover and had a general idea of what to write in each chapter, things went pretty smoothly. I was able to write a chapter in a weekend so I was ahead of schedule most of the time.

Turns out that writing a chapter is not the hard part, the grind comes when you have to edit, re-edit, and incorporate all the rounds of feedback. The editing part is much less creative than starting from a blank page, but is equally if not more important.

I completed the draft mid-May and incorporated the last round of external feedback by July. Beyond the chapters, there is also a Front Matter, inside covers, and appendices, which I worked on in July/August.

All in all it took about a year from when I started outlining the book on GitHub to having the final version ready to go to production.

Production

From then on, the book goes to production and another set of people goes over the spelling, layout, indexing and so on. At this stage, my responsibility was mostly to review changes and suggest minor updates.

Last week I received the final PDF version of how the book will look like in print, and today I was notified it is being sent to the printer.

Writing the book was a great experience and I got the chance to work with some wonderful people. I hope the final product is a good book which leads to better software.