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.
Continue reading about First lessons learned about writing technical books
Semantically similar articles hand-picked by GPT-4
- I published a book with a publisher. Here's what the journey was like.
- After five months, my effective hourly rate with a publisher is 3eur/hour
- It took me ten months to write a video course
- It takes about two months to write a technical book
- How a book I wrote in two weeks made $4,000 in its first month
Learned something new?
Read more Software Engineering Lessons from Production
I write articles with real insight into the career and skills of a modern software engineer. "Raw and honest from the heart!" as one reader described them. Fueled by lessons learned over 20 years of building production code for side-projects, small businesses, and hyper growth startups. Both successful and not.
Subscribe below 👇
Software Engineering Lessons from Production
Join Swizec's Newsletter and get insightful emails 💌 on mindsets, tactics, and technical skills for your career. Real lessons from building production software. No bullshit.
"Man, love your simple writing! Yours is the only newsletter I open and only blog that I give a fuck to read & scroll till the end. And wow always take away lessons with me. Inspiring! And very relatable. 👌"
Have a burning question that you think I can answer? Hit me up on twitter and I'll do my best.
Who am I and who do I help? I'm Swizec Teller and I turn coders into engineers with "Raw and honest from the heart!" writing. No bullshit. Real insights into the career and skills of a modern software engineer.
Want to become a true senior engineer? Take ownership, have autonomy, and be a force multiplier on your team. The Senior Engineer Mindset ebook can help 👉 swizec.com/senior-mindset. These are the shifts in mindset that unlocked my career.
Curious about Serverless and the modern backend? Check out Serverless Handbook, for frontend engineers 👉 ServerlessHandbook.dev
Want to Stop copy pasting D3 examples and create data visualizations of your own? Learn how to build scalable dataviz React components your whole team can understand with React for Data Visualization
Want to get my best emails on JavaScript, React, Serverless, Fullstack Web, or Indie Hacking? Check out swizec.com/collections
Did someone amazing share this letter with you? Wonderful! You can sign up for my weekly letters for software engineers on their path to greatness, here: swizec.com/blog
Want to brush up on your modern JavaScript syntax? Check out my interactive cheatsheet: es6cheatsheet.com
By the way, just in case no one has told you it yet today: I love and appreciate you for who you are ❤️