Anton and myself were interested in the topic because our day job was working at Disqus, the embedded commenting platform. At the time there really wasn’t a guide for how to solve a lot of the problems we were facing. Problems like how to make
Array.prototype.pushhave been replaced with custom incompatible versions. We spent a lot of time – and sometimes late nights – figuring out those answers.
But we didn’t wake up one morning and decide on that pitch, or even plan to write a book at all. A series of events led us to even thinking of writing one. And it would take years after that before we’d hold the book in its final published form.
It started with a conference talk
It was summer of 2010. I was just a few months into working at Disqus, whom I had joined after spending 3 years doing traditional LAMP stack + “AJAX” development at FreshBooks in Toronto.
Disqus is where I first met my future co-author, Anton, who’d already been working there a year before I showed up. It’s Anton who first introduced me to the Disqus codebase, walking me through how they’d made an entire commenting and moderation UI that loaded via a single third-party
<script> tag. We literally sat side-by-side, often working together on the same projects, and frequently conferring with eachother on ideas, code, and typical programmer bikeshedding.
The timing probably couldn’t have been better. The Facebook Like button had been out for a year at this point, and Twitter had just launched their own 3rd-party Tweet button. On top of that, Disqus itself was having a moment. Many web development thought leaders were switching their blogs to static site generators like Jekyll, and they began using Disqus to host dynamic comments on otherwise-static HTML documents. This blog included.
Still, I was surprised when the talk was accepted and announced that September as part of jQuery Conf Boston 2010. You can view the slides here. It covered some of the things I’d learned that year, like how to use JSONP,
window.postMessage, and why iframes are so important. It was also my first conference talk, and I wanted very badly not to embarrass myself in front of a room of smart people. I ended up missing much of the conference, opting instead to practice repeatedly in front of my hotel room’s bathroom mirror.
I don’t remember leaving the conference with any grand ambition to continue this work. But a few months later, I received an email that would dramatically change the trajectory of the next few years.
“Have you considered writing a book?”
It was now January 2011, and someone at Manning Publications sent me an email. They were emailing folks who had presented at jQueryConf the previous fall to see if anyone was interested in developing their talk material into a book.
“Was that something you wanted to explore?”
I can’t remember the exact order of events, but it’s at this point that I approached Anton to write the book with me. We’d been working together for the past year now, the jQueryConf talk content was based on both of our work, and he assisted me in vetting the slides. But perhaps most importantly, I wanted Anton because I didn’t think I could do it alone.
To do that, we filled out a standard template provided by Manning where we had to explain the book’s title, who it’s for, what readers will learn, highlight any competing books, etc. Manning also wanted a detailed table of contents, for which you were expected to define not just each chapter, but each chapter’s sections and subsections. This was to demonstrate that you had enough content to fill a 300 page book, which was kind of a must at the time (the sub-100 page book market that O’Reilly would later pioneer hadn’t happened yet).
You can read this original proposal here.
After Manning first expressed interest, we did reach out to O’Reilly to see if they’d also consider publishing the book. But even with a referral from a friend, the response came off as “sure kid, fill out this form”. We never bothered to, and O’Reilly didn’t follow-up. We spoke to other credible authors who’d published with Manning, like Yehuda Katz (jQuery in Action), and felt comfortable to move forward with them.
On the strength of this proposal and our passionate conference-call gesticulating, Manning decided to go forward. And what started as a conference talk proposal just 6 months earlier had turned into a contractual obligation to deliver a 300 page book. What had we wrought?
Actually writing a book
One of the reasons we wanted a publisher is that even though there were two of us, Anton and I did not have a lot of confidence that we could actually write an entire book ourselves. We had read more than a few “so you want to write a book” blog posts, and as a result we weren’t deluded about the colossal scope of work we were taking on. We wanted all the help we could get.
Manning and most other publishers have systems for developing books, and by agreeing to publish a book with them you’re agreeing to use that system. For example, Manning pairs you with an editor and some handlers, commits you to a schedule for delivering chapters, and they have a process for getting feedback from readers early and often. The book becomes available for purchase early as part of their Manning Early Access Program (MEAP), and folks have a chance to read early chapters and comment before the book is finished. Access to this “Manning method” was a big plus.
When it came to the actual writing, Anton and I decided that the fastest way forward was to divide the book up. Each of us would tackle different parts, playing to our strengths. I focused on the early chapters, setting up the example application the reader would be building over the course of the book, as well as the initial concepts (loading scripts, Same-Origin Policy, JSONP, etc.). Anton worked on the middle and later chapters (e.g. Performance, Security, etc), which had more technical focus.
Joining us from Manning’s side was Renae Gregoire, who was simultaneously our editor, book-writing spirit guide, and taskmaster. She taught us how to write better by using Manning’s house style, let no reference go unexplained, and was diligent in reminding us about our many deadlines.
I can’t speak for other technical authors, but Anton and I did not have all the answers in our heads. We often had to get those answers, by researching, tinkering with code, and consulting with peers. We did not want to come off as frauds, so we implemented every example and technique presented in the book (as one should!), and shipped those as part of the the accompanying source code. This all took a lot of time.
Despite our best efforts, we were behind schedule almost from the very beginning. But after we delivered the first 1/3 of the book, we felt like we were getting the hang of things and progress became a lot more steady.
By March of 2012 – one year after we’d signed the contract with Manning – we had delivered drafts of all 10 chapters (albeit, in varying states of quality). MEAP readers already had access to the first 6 chapters, we were approaching 1,000 preorders, and Anton and I felt ready to pop the champagne.
The remaining 10%
The first 90 percent of the code accounts for the first 90 percent of the development time. The remaining 10 percent of the code accounts for the other 90 percent of the development time. — Tom Cargill, Bell Labs
This quote may have been referring to software development, but I think it equally applies to book writing. Even though we had “finished” all 10 chapters in one year, it would be another year until the book actually went to print.
A key reason for this slowdown was how the book itself was being assembled. At the time, Manning used an in-house XML schema to structurally represent the content, which aided them in publication (and necessary for producing early-access editions). Writing an entire book in XML wasn’t appealing, so Anton and I would write our initial drafts in Google Docs, and only convert them to XML after our editor had made a few passes. But once these XML files were stored in Git and became the source of truth, any subsequent editing had to happen there.
That worked great in the beginning, but now that all 10 chapters were done, we had to go back repeatedly and edit XML without the benefit of a word processor. And boy, did we have to do a lot of editing:
- adjusting the book’s voice to sound like a single person
- fixing flaws and typos pointed out by reviewers
- adding and revising diagrams, code samples, etc.
- rewriting whole sections that didn’t work, then going through the entire book to remove any references to those sections
Doing all of this in XML made the work a real slog. And the way the review cycle works, where you hand in early access versions to reviewers, wait weeks for feedback, make edits, and repeat, was adding to the challenge. It felt like trying to land a monster 50,000 line PR that was stuck in code review hell, and after going back and forth for months we just wanted to hit merge and move on with our lives. We were crawling towards the finish line.
In the end the Manning stuck with our preferred title (🙏). We instead tried to broaden the subject matter as much as possible, by highlighting every possible use case, making sure the sample code worked on Windows, and even added adjacent content (e.g. a chapter on Testing).
We tried to make it accessible as we could. But was it enough?
The reviews are in
The book came out in March 2013, almost exactly 2 years since the contract was signed. Disqus hosted a launch party for us in San Francisco (they were supportive of the project beginning to end). Manning sent Anton and myself about a dozen copies each, which mostly found their way to friends and family. I only signed a handful, so if you’ve got one, hang onto it!
Despite my minor grumblings, I feel working with Manning was a net positive. I’m not sure we could have done it without them, really. 100% if we had tried to Kickstart this book, I am confident it would have been vaporware and we’d be accused of embezzling Kickstarter funds.
And ultimately, Manning’s concerns about the lack of broad appeal were valid. Consider this review from Raymond Camden in 2013:
This summarizes the challenge well: Raymond didn’t think there would be anything in this book for him. And yet …
I cannot stress how wrong I was. While certainly the book does focus in on embedding code in other web sites, the level of detail and coverage of various browser quirks makes this book invaluable to anyone.
… If you have no plans ever for building a third-party API, this book is still strongly recommended. Hell, the last two chapters alone on performance and debugging are worth the price of the book alone. This is a book I plan on keeping nearby as I feel like I’ll be tapping the knowledge inside again and again.
Some other reviews (I’m trying not to cherry pick):
- Goodreads – currently 4.08/5 with 48 ratings
Did people read it?
Our post-book periods
By the time the book had come out, Anton was already better known as the creator of JSHint, a static type checker that began as a fork of JSLint. JSHint was really a pioneer in driving people away from the “best practices-or-bust” approach of JSLint. It was superceded by ESLint, for which extensive configuration was a signature feature. There’s a lot more I could write about JSHint, but I’ll leave that for Anton.
As for me … After the book came out, I started going on the speaker circuit for a few years. Some conferences would invite me (super flattering), but most I probably wrote CFPs for. As before, most of the content came from new problem areas I was solving during my day job, like Content Security Policy, or how to replicate the briefly-exciting-but-now-dead seamless iframe attribute.
I guess this turned into my own “so you want to write a book” story. I hope it serves as a mildly interesting example of how people get involved in programming topics, and what can happen should they pursue sharing what they’ve learned with the broader community.
If you’re working on something you find interesting right now, I encourage you to consider that there are probably people out there who’d like to hear about it. Consider blogging about it, or sharing a quick video on socials, or maybe even putting together a conference proposal. You never know where it might lead!
Thank you to Anton Kovalyov, Talton Figgins, and Adit Bhargava for reviewing this post. If any title gives me faith that programming books aren’t dead yet, it’s Adit’s Grokking Algorithms. The 2nd edition is coming out in a couple months. Check it out!