A while ago a publisher contacted me to write a book on d3.js.
Even though I once managed to create a picture with d3.js and wrote a quick tutorial about it on my blog, I didn’t really know much about the library. It’s a seriously confusing piece of technology that almost seems more black magic than common sense.
Explains the loud clamouring for books on the topic. (two have been published so far)
After a few months of back and forth the contract was penned and signed, two weeks ago I finished the procrastination stage and started writing.
I’m learning a lot writing this book, suddenly d3 is no longer a mystery only mbostock and New York Times know how to use … I’d go so far as saying the book will be better because I’m writing it as I learn because I still remember which parts need more attention.
This being my first technical book and my first book with a real publisher and ISBN number, I’m learning more than just d3.js.
1. You will write more than you think
Starting out, the publisher asked me to create an outline with a rough estimate of how many pages each chapter is going to be. I was supopsed to create a 100 page book and, to be honest, that seemed like an insurmountable task.
A hundred pages! That’s, dude, that’s like a real book! I can’t write a hundred pages about something I don’t know, are you insane?
But write an outline I did. I looked at each chapter, furrowed my eyebrow, twisted my lip into a grimace, and wrote down an imaginary number. This chapter will be 10 pages long! This one will be 30! Yes, that sounds about right.
The number of pages evenly summed up to 100. Perfect!
Then I started writing. The first chapter was going to be a 10 page quickstart into the world of d3.js, I would show you how to set up the environment for the rest of the book and explain three quick visualisations. Get something working within the first 2min of reading a book, y’know?
It took me 10 pages to rush through a single example. Yes, rush through. You get the depth of nothing, but you might be able to perform some inference learning and do stuff on your own.
I am currently writing the second chapter, a 30 page deep explanation of the basics, at 36 pages I have covered about 70% of the material … and that’s including the buildup of knowledge that makes code explanations progressively less detailed.
Code samples, their explanations and plenty of images since we’re writing about, well, images builds up fast.
2. You have no idea how much time you need
Despite the insane amount of content you will create explaining basic concepts you previously thought were self-explanatory, writing a technical book is a stupidly slow process.
Perhaps because I’m spending as much, if not more, time learning the material myself, playing around to see what things are doing and so on … but it just takes time. A lot of it.
The publisher didn’t pull their deadlines out of thin air. Well they did, but they asked me to approve them. Oh, what, I have until March to write this? And it’s only December? Sure, that sounds perfectly reasonable!
Then the first full writing weekend happened. When it was over I was the proud owner of slightly more than a first chapter. In fact, I had the whole first chapter and what I thought was a third of the second chapter.
It had taken three days to write 20 pages.
I was exhausted, I was dreaming SVG and HTML. It was terrible. Suddenly the deadline was super close. I could feel it nipping at my heels, smell its ugly breath as steam escaped its nostrils, I could almost feel its yellow teeth brushing against my thigh.
Then you notice you forgot to explain something. But it doesn’t fit at the end of the chapter because it would ruin the flow. You put it in the beginning and voila, just like that, you have to change some 20 screenshots.
3. This is not creative writing. By far.
The thing that really gets me most, though, is that writing a technical book is just not very creative. I know I know, a good writer can make any piece of writing fun and I certainly hope I’m making the book an entertaining read.
Writing it, though, is just not fun. It’s work.
Schlep work through and through. You create an example. You have fun creating an example. You could spend countless hours just playing around, finding out how things work.
Sometimes you do spend hours searching for a good example to illustrate your point without relying on the concepts you have yet to teach the reader. Then you avert your eyes to the other screen. Grab your keyboard. And write.
Explaining every little detail, making sure you didn’t gloss over anything, keeping the reader engaged and interested … it’s … it’s just a little bit boring, you know? Sometimes I feel like an idiot for explaining something, like I’m insulting the reader by not assuming they know that crap.
Then you show the writing to a friend who is a good representation of the target audience – Hey, can you explain that a bit more? You kind of glossed over it. I am surprised and confused. Your example is terrible.
So yeah …
Right now I’m writing two books at the same time. That was a terrible, horrible idea, but here we are. I’m supposed to finish the d3.js book by March. I might have a chance at meeting that deadline.
I’m afraid it is unlikely that the Why Programmers Work at Night book should get an update in February. This makes me sad.
But what makes me even more sad is that I am not entirely certain the publishing contract allows me to post this blogpost. I think it’s okay because I didn’t mention the publisher or the title. I am also uncertain whether I’m allowed to show the drafts to my friends, that’s a bit of a grey area.
Going to be showing the drafts to my friends anyway. Editor feedback is measured in months. A travesty really, feedback loops should be quick and efficient.
Learned something new? Want to improve your skills?
Join over 10,000 engineers just like you already improving their skills!
Here's how it works 👇
PS: You should also follow me on twitter 👉 here.
It's where I go to shoot the shit about programming.