Thoughts by Bruno Bernardino

Writing a book

My experience of writing Pro jQuery Plugins

December, 2013

My Book: Pro jQuery Plugins

An unexpected invitation

I’ve never thought about writing a book.

I had some ideas for Sci-fi books and I was good at writing poems, but it was never something I aspired to do.

In August 2012, however, I was invited by a great and well-known American publisher to write a book about JavaScript for experts. I ended up choosing to write about jQuery Plugin Development for Pros. There weren’t many great books available that I knew about, and it was something I felt there was a need to exist.

I accepted writing the book merely because it was a new challenge I had never faced. I like those kinds of challenges. I was really excited about it.

First steps

I had no clue about writing a book, even though I had written a few very successful web development tutorials and opinion related blog posts for a well known Portuguese blog, Pplware.

Boy, was I in for a surprise.

The first strange thing about it, was when they asked me to provide a full chapter outline, with a pages count estimate for each chapter, before the book got approved to be started by the publisher.

The book also had to have a predefined number of pages, and each chapter a maximum number of pages. This made no sense to me, but they were the experts.

Remember: I had no idea what the book was supposed to even look like, but I had to make a very accurate estimate as to how it would turn out to be.

I get that this helps a bit in the process of you defining what you will talk about, and what will be your topics, but it should be a flexible outline, not a strict, unbending, final definition, with page counts. Specially because I haven’t even started writing it.

Problems before starting to write

The first problem came in: they have never worked with Markdown.

I suggested sharing with Google Docs. It was ok to share the chapter outline and the introduction draft, but they wanted me to use a Word template.

It was awful.

Anyone who knows me, knows I’m averse to most Microsoft technologies and products.

I itched at the thought of having to buy and install Office, and I suggested to continue using Google Docs, providing the content, and their editors would put it on Word and do their thing.

They helped me out in the first chapters, but I was doomed to buy a license for Office, and having to use Word to send my chapters. Worse than that, I had to use SharePoint to collaborate with them, sharing my chapters there.

This was the second worst part of the experience.

SharePoint doesn’t even work well with Google Chrome, so I had to use Firefox (luckily, I didn’t have to use my virtual machine with Windows to upload the documents!) to upload the documents, email them explaining I had uploaded, wait for them to email me with revisions (because SharePoint wouldn’t notify me or them about any changes), download from there, work with Word’s awful comment system (that tends to crash out of the blue), and upload it again.

Basically, what I ended up doing was writing with iA Writer (Markdown FTW!), pasting on Google Docs (to “version control”, slightly style the code, etc.), and then pasting everything on Word, styling according to their guidelines.

It was painful, but less painful than having to use only Word.

We love it, but… it’s too much code?

They loved my initial chapters, about coding guidelines, best practices and optimizations (a few problems about the screenshots, though, because they weren’t “appropriate”), but as soon as I started uploading my chapters with plugin samples (with lots of code), other problems started showing up.

They were complaining my chapters had “too much code” and “little explanations”. It turns out that even though this book was supposedly for “Pros”, I had to explain what a “skeleton plugin” was, what was “event binding” and why it was needed, etc. I explained that, if I was writing for intermediate to advanced developers, these things required no explanation, and would just bore the readers.

The fact there were several lines of code without “text” (interruptions) was also very worrying for them. It would look bad in a book and would be “too much code” to “digest” in one take.

I get that you need to break the code in small parts to properly explain “each line”, when you’re writing a book for beginners. It doesn’t make sense to me to do it for Pros, though. It’ll be noise.

I was careful enough to explain many things inside the code itself, in block lines and block comments, so that reading the code made sense for anyone.

I was also careful enough to make the variable and method names meaningful.

I was trying to focus on a book that I would want to read and learn from. They were aiming for something else, apparently.

Eventually, they understood my point and agreed that comments in the code made sense.

Tight deadlines

Another big problem was the strict deadlines to give them the chapters. 12 days per chapter is very short, especially when you have a full-time job and the reviews/revisions of previous chapters start piling up.

I was also getting a bit annoyed by them removing some of my jokes and “personal voice” from some chapters.

I came across this article on Tuts+ that seemed like a very accurate expression of my experience.

All publishers should really read it. It felt good to know I wasn’t alone in this frustrating process.

Pause… and stop.

Fortunately, the book was halted for about a month, due to an unfortunate event (they were having problems sending me a payment, it was already delayed by over a month when I decided to halt it), and that gave me some time to focus on other things, relax about the book, and when I re-started on it, I had a lot of ideas and energy.

The two biggest plugin samples were still to be done, and I was excited about them.

Sadly, when the book was near completion (just a chapter and appendices missing), the publisher backed out and didn’t want to publish what I had written.

It wasn’t “book material”, but rather “web material”, in their opinion. It had too much “code” and little “text”.

I wasn’t expecting it because I didn’t change from what I said I would do or anything, and they had agreed to it anyway. However, I wasn’t mad and felt a kind of relief.

Maybe “normal books” aren’t for me.

Going solo

I ended up deciding to publish the book in eBook format on my own, because of the feedback I had gotten from a few excerpts

I had shown some developer friends, and because I believed in what I had written.

Having total creative control about the book made me very excited about it again, and I went on to put back my “personal voice” into it, rearrange a few things, and uninstall Word!

I really hope people like it, as I’m really proud of the final product.

Bruno Bernardino

Written by Bruno Bernardino.
Thoughts can change, disappear, or simply be observed.

Go back to all thoughts.