13 Tips for Writing a Technical Book

May 26, 2019

I spent the last year and a half writing my first technical book for O’Reilly (Programming TypeScript). I’d never written a technical book before. In fact, prior to the 300-page book, the longest thing I’d written was a 20-something-page paper in college.

Why’d I write the book? I love TypeScript, and I didn’t see any great resource out there that explained not just the language and build system features, but went deeper to explain why things were designed the way they were, how the different parts of the language fit together, how that compares to other languages out there, and how it all looks in practice. Those are the sorts of things you can only learn through lots of research and practice, and that was sorely missing from the handful of relatively brief and practical TypeScript guides out there today.

The rest of this post is a brief laundry list of tips for writing your own technical book.

Getting a book deal

Make ‘em fight for it. One day, I got a cold email from Packt Publishing asking me to write a book on TypeScript. I’d actually been thinking about the idea for a few months, having sent a series of unreturned cold emails to an O’Reilly acquisitions editor pitching a handful of topics to write about (one that’s close to my heart, which I hope to revisit someday, is a book that teaches you functional programming in JavaScript, starting from basic middle school algebra). I really wanted to write a book for O’Reilly since they published a bunch of the technical books that I’d learned from over the years (Zakas’ excellent High Performance JavaScript and Grigorik’s High Performance Browser Networking are a couple of my favorites). So I forwarded Packt’s email to O’Reilly, and got a response the next day that O’Reilly was interested, and that I should send over an outline and a timeline. We had a signed contract within the week – I’d get 10% of print sales, plus 25% of digital sales.

Pad the timeline. Like any other engineering project, the time you think it will take to write a book is going to end up being a fraction of the time it actually takes. Why? Even if you’re a subject matter expert with an outline in hand, there are a lot of unknowns: the time it takes to do research; the time it takes to come up with good examples; the time it takes to derive reference implementations; the number of times you delete and re-write sections to get them right; the overhead of coordinating contributors, and so on. Take your estimate, and pad it like you would an engineering estimate. For example, I estimated 8 months, while it actually ended up taking 15.

Writing

Start with an outline. Without a clear idea of what you’ll cover, it’s easy to get off-topic. It’s also easy to get burnt out from the sense of having a lot of content left to cover with no clear sense of progress or of what’s left. With an outline, it’s easy to know how far you’ve come, and how long you have left to go.

Schedule regular time to write: every morning, every weekend, etc. With a full-time job, it can be hard to find time to write. And when you’re not writing, you might feel guilty that you’re not writing, which can lead to stress. That’s why blocking off regular time to write is key. My schedule was most Saturdays and Sundays, from 9am to 6pm. I also noticed that mornings were by far the most productive for me: while in the morning I could often get into a state of flow, this was much harder to do at night. Rinse and repeat: doing this every weekend, for months at a time, I steadily chipped away at my outline.

Get feedback early, get feedback often. Like starting a business, you’ll often have intuition about what problem needs to be solved by your book. And like a business, you’re going to get a lot of the details wrong at first. To make sure you’re on the right track, get as much feedback as you can from potential readers: show your outline to colleagues before you write, run your drafts by friends and readers recommended by your editor (I asked O’Reilly for this on a couple of occasions); get as much feedback as you can, as early as you can. In Andy Grove’s words, “a common rule we should always try to heed is to detect and fix any problem at the lowest-value stage possible”.

Keep a running list of stylistic conventions. You’re going to have to form a point of view on a huge number of stylistic conventions as you write. For me, that included things like whether to use tabs or spaces, semicolons or no semicolons, how to consistently represent inferred types in code blocks (I used comments), how to consistently represent evaluated results in code blocks (I used comments prefixed with “evaluates to”), how to represent function and method names when talking about a function (fn, fn(), .fn, or .fn()?), and so on. There’s a lot of decisions to make, and you won’t be able to make all of them upfront. Keep a running list, and when you make up your mind about one, go back and update your manuscript to conform to that convention. The earlier you can make up your mind, the easier it will be to update everything.

Use lots of TODOs to keep track of what’s left. Anytime you want to revisit something – a missing code sample, a section that reads weird and should be re-worded, a section that you don’t feel like writing at this very moment and want to circle back on later – leave a TODO. It’s easy to grep for later on, and it’ll help make sure you don’t miss anything.

Editing

When editing, print out your manuscript and edit it with a red pen. Yes, I mean with a real pen, on real paper. There’s a lot of issues you’ll catch this way that you won’t notice on screen: from grammatical errors and formatting, to discontinuities, to explanations that could use more work. Also, it feels fancy to sit at a cafe and edit a 300-page stack of papers in pen (unless you’re a teacher, in which case you’re thinking “that’s cute”).

Read your manuscript all the way through. It might sound surprising, but after months spent writing it’s not easy to pause and take the time to read throught everything you just wrote. When you read all the way through your manuscript, you’ll notice issues that you wouldn’t have noticed when reading through a section or a chapter at a time. Certain kinds of problems you’ll only be able to find this way: things like stylistic inconsistencies (eg. you used capitalized comments in one place, and lowercased in another place), discontinuities (eg. you covered a topic twice, or forgot to give context for something), and so on. This sort of editing can be exhausting, but is critical to a high-quality result. Think of it as dogfooding.

Expert reviewers won’t give you as much as you want. While reviewers suggested by O’Reilly were super helpful as a sanity check, they won’t give you the deep domain-specific insights and pushback that you want. They’ll review for high level structure and comprehension, but won’t go into details like “is this the right way to derive a Promise type?” or “is this statement about module loading technically correct?”. More generally–

Getting good technical editors is hard. While O’Reilly provided good technical editors, I had to seek out subject matter experts myself and convince them to look at my manuscript. To do that, I asked a few friends, and emailed a bunch of people that I’ve met via Github and on Meetup to ask if they’d like to take a pass through my manuscript. Of course, that’s a giant ask that comes with a significant time commitment and little pay-off (O’Reilly can front technical editors a few hundred bucks as a thank you, which can feel inadequate for the 10+ hours an editor might spend editing your manuscript). Despite that, Daniel Rosenwasser from the TypeScript team offered to step in and edit. His contributions were the most valuable edits I recieved by an order of magnitude, and I’m immensely grateful for his taking the time to give feedback on my manuscript.

Misc.

While getting good technical editors is hard, getting good contributors is harder. Initially, I was hoping to get a range of contributions by subject matter experts: someone to talk about module loading, someone to talk about reactive programming, people to talk about React, Vue, and Angular. Turns out, a lot of subject matter experts don’t have time to do that. Of the dozen contributors that I planned to recruit, I ended up with two, one of which O’Reilly suggested. For these two contributors, it took a lot of work to get their contributions to a place where I could integrate them with my manuscript: back-and-forth on what content they should include, updating formatting, and integrating their sections with the rest of the manuscript. Eventually, I ended up re-working their sections significantly. As an author you have a lot of opinions about how to best present content, which can be hard to reconcile with other contributors – unlike collaborating on code, where you can enforce conventions with frameworks and linters, it’s a lot harder to be on the same page when it comes to writing style.

Writing is lonely (Ben Horowitz said it first). No one knows better than you whether to write A or B, what’s the right way to explain something, or whether or not your solution is actually correct. No one can tell you whether one way to explain something is better than another way. You’re going to spend an inordinate amount of time by yourself, at a cafe or at home, going back and forth on different ways to do something, wincingly playing out in your mind the reactions from the community (“This is the worst idea ever!”; Or, “this is ground-breaking stuff!”). Explore different ways to do a thing and run it by as many people as you can; then, pick an option – no one else can do that for you.

If you’re just starting to write your technical book, or have been thinking about taking the leap, I hope this list helps you. Am I missing anything? Shoot me an email with edits, additions, or insinuations.