Swizec Teller - a geek with a hatswizec.com

    First lessons learned about writing technical books

    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.

    Enhanced by Zemanta

    Did you enjoy this article?

    Published on January 29th, 2013 in HTML, New York Times, Publish, Technology, Uncategorized, Writers Resources

    Learned something new?
    Want to become an expert?

    Here's how it works 👇

    Leave your email and I'll send you thoughtfully written emails every week about React, JavaScript, and your career. Lessons learned over 20 years in the industry working with companies ranging from tiny startups to Fortune5 behemoths.

    Join Swizec's Newsletter

    And get thoughtful letters 💌 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. 👌"

    ~ Ashish Kumar

    Join over 14,000 engineers just like you already improving their careers with my letters, workshops, courses, and talks. ✌️

    Have a burning question that you think I can answer? I don't have all of the answers, but I have some! Hit me up on twitter or book a 30min ama for in-depth help.

    Ready to Stop copy pasting D3 examples and create data visualizations of your own?  Learn how to build scalable dataviz components your whole team can understand with React for Data Visualization

    Curious about Serverless and the modern backend? Check out Serverless Handbook, modern backend for the frontend engineer.

    Ready to learn how it all fits together and build a modern webapp from scratch? Learn how to launch a webapp and make your first 💰 on the side with ServerlessReact.Dev

    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 ❤️

    Created by Swizec with ❤️